@back23/promptly-sdk 1.3.0 → 1.3.1

package/README.md

@@ -1,17 +1,17 @@
-# @webbyon/promptly-sdk
+# @back23/promptly-sdk
 
 Promptly AI CMS SDK for JavaScript/TypeScript
 
 ## Installation
 
 ```bash
-npm install @webbyon/promptly-sdk
+npm install @back23/promptly-sdk
 ```
 
 ## Quick Start
 
 ```typescript
-import { Promptly } from '@webbyon/promptly-sdk';
+import { Promptly } from '@back23/promptly-sdk';
 
 const client = new Promptly({
   tenantId: 'demo',
@@ -19,6 +19,38 @@ const client = new Promptly({
 });
 ```
 
+## v1.3.0 Changes
+
+### Unified Response Structure
+
+All list APIs now return a consistent `ListResponse<T>` format:
+
+```typescript
+interface ListResponse<T> {
+  data: T[];  // Always an array (never null/undefined)
+  meta: {
+    current_page: number;
+    last_page: number;
+    per_page: number;
+    total: number;
+    from: number | null;
+    to: number | null;
+  };
+}
+```
+
+**No more defensive code needed:**
+
+```typescript
+// Before (v1.1.0)
+const posts = await client.blog.list();
+const items = posts?.data ?? [];  // Defensive check needed
+
+// After (v1.3.0)
+const { data, meta } = await client.blog.list();
+data.map(post => ...);  // data is always an array
+```
+
 ## API Overview
 
 | Resource | Public (No Auth) | Protected (Auth Required) |
@@ -26,12 +58,13 @@ const client = new Promptly({
 | **Boards** | list, get | - |
 | **Posts** | listPosts, getPost | createPost, updatePost, deletePost |
 | **Comments** | listComments | createComment, updateComment, deleteComment |
-| **Blog** | list, get | - |
+| **Blog** | list, get, featured, byCategory, byTag | - |
 | **Shop** | listProducts, getProduct, listCategories | getCart, addToCart, listOrders, createOrder |
 | **Forms** | list, get, submit | mySubmissions |
 | **Auth** | login, register | logout, me, updateProfile |
 | **Media** | - | upload, list, delete |
 | **Entities** | list, getSchema, listRecords, getRecord | createRecord, updateRecord, deleteRecord |
+| **Reservation** | getSettings, listServices, listStaff, getAvailableDates, getAvailableSlots | create, list, get, cancel |
 
 ## API Reference
 
@@ -39,20 +72,20 @@ const client = new Promptly({
 
 ```typescript
 // 게시판 목록
-const boards = await client.boards.list();
-// Returns: Board[]
+const { data: boards, meta } = await client.boards.list();
+// Returns: ListResponse<Board>
 
 // 게시판 상세
 const board = await client.boards.get('first'); // slug or id
 // Returns: Board
 
 // 게시판 글 목록
-const posts = await client.boards.listPosts('first', {
+const { data: posts, meta } = await client.boards.listPosts('first', {
   page: 1,
   per_page: 10,
   search: '검색어', // optional
 });
-// Returns: { data: BoardPost[], meta: { current_page, last_page, per_page, total } }
+// Returns: ListResponse<BoardPost>
 
 // 글 상세
 const post = await client.boards.getPost(1);
@@ -60,7 +93,7 @@ const post = await client.boards.getPost(1);
 
 // 댓글 목록
 const comments = await client.boards.listComments(1);
-// Returns: BoardComment[]
+// Returns: BoardComment[] (always an array)
 ```
 
 ### Posts & Comments - Protected (로그인 필요)
@@ -105,14 +138,14 @@ await client.boards.deleteComment(commentId);
 
 ```typescript
 // 블로그 글 목록
-const posts = await client.blog.list({
+const { data: posts, meta } = await client.blog.list({
   page: 1,
   per_page: 10,
   category: 'news', // optional
   tag: 'featured',  // optional
   search: '검색어', // optional
 });
-// Returns: { data: BlogPost[], meta: {...} }
+// Returns: ListResponse<BlogPost>
 
 // 블로그 글 상세
 const post = await client.blog.get('post-slug');
@@ -120,13 +153,21 @@ const post = await client.blog.get('post-slug');
 
 // 추천 글
 const featured = await client.blog.featured(5);
-// Returns: BlogPost[]
+// Returns: BlogPost[] (always an array)
 
 // 카테고리별 조회
-const newsPosts = await client.blog.byCategory('news');
+const { data: newsPosts } = await client.blog.byCategory('news');
 
 // 태그별 조회
-const taggedPosts = await client.blog.byTag('featured');
+const { data: taggedPosts } = await client.blog.byTag('featured');
+
+// 카테고리 목록
+const categories = await client.blog.categories();
+// Returns: string[] (always an array)
+
+// 태그 목록
+const tags = await client.blog.tags();
+// Returns: string[] (always an array)
 ```
 
 ### Shop (쇼핑)
@@ -135,14 +176,14 @@ const taggedPosts = await client.blog.byTag('featured');
 
 ```typescript
 // 상품 목록
-const products = await client.shop.listProducts({
+const { data: products, meta } = await client.shop.listProducts({
   page: 1,
   per_page: 10,
   category: 'electronics', // optional
   is_featured: true,       // optional
   search: '검색어',        // optional
 });
-// Returns: { data: Product[], meta: {...} }
+// Returns: ListResponse<Product>
 
 // 상품 상세
 const product = await client.shop.getProduct('product-slug');
@@ -150,11 +191,11 @@ const product = await client.shop.getProduct('product-slug');
 
 // 추천 상품
 const featured = await client.shop.featuredProducts(8);
-// Returns: Product[]
+// Returns: Product[] (always an array)
 
 // 카테고리 목록
 const categories = await client.shop.listCategories();
-// Returns: ProductCategory[]
+// Returns: ProductCategory[] (always an array)
 ```
 
 #### Protected (로그인 필요)
@@ -195,8 +236,8 @@ const order = await client.shop.createOrder({
 });
 
 // 주문 목록
-const orders = await client.shop.listOrders();
-// Returns: { data: Order[], meta: {...} }
+const { data: orders, meta } = await client.shop.listOrders();
+// Returns: ListResponse<Order>
 
 // 주문 상세
 const order = await client.shop.getOrder(orderId);
@@ -208,6 +249,89 @@ await client.shop.cancelOrder(orderId);
 // 쿠폰 검증
 const validation = await client.shop.validateCoupon('SAVE10', 50000);
 // Returns: { valid: boolean, discount_amount: number, coupon: Coupon }
+
+// 내 쿠폰 목록
+const coupons = await client.shop.myCoupons();
+// Returns: Coupon[] (always an array)
+```
+
+### Reservation (예약) - NEW in v1.3.0
+
+#### Public (로그인 불필요)
+
+```typescript
+// 예약 설정 조회
+const settings = await client.reservation.getSettings();
+// Returns: ReservationSettings
+
+// 서비스 목록
+const services = await client.reservation.listServices();
+// Returns: ReservationService[] (always an array)
+
+// 담당자 목록
+const staffs = await client.reservation.listStaff();
+// Returns: ReservationStaff[] (always an array)
+
+// 특정 서비스의 담당자만 조회
+const serviceStaffs = await client.reservation.listStaff(serviceId);
+
+// 예약 가능 날짜 조회
+const dates = await client.reservation.getAvailableDates({
+  service_id: 1,
+  staff_id: 2,        // optional
+  start_date: '2026-01-01', // optional
+  end_date: '2026-01-31',   // optional
+});
+// Returns: string[] (YYYY-MM-DD format)
+
+// 예약 가능 시간 슬롯 조회
+const slots = await client.reservation.getAvailableSlots({
+  service_id: 1,
+  date: '2026-01-15',
+  staff_id: 2, // optional
+});
+// Returns: ReservationSlot[]
+```
+
+#### Protected (로그인 필요)
+
+```typescript
+// 예약 생성
+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
+});
+// Returns: { reservation: Reservation, requires_payment: boolean, deposit: number }
+
+// 내 예약 목록
+const { data: reservations, meta } = await client.reservation.list({
+  status: 'confirmed', // optional
+  upcoming: true,      // optional
+  past: false,         // optional
+});
+// Returns: ListResponse<Reservation>
+
+// 다가오는 예약
+const upcoming = await client.reservation.upcoming(5);
+// Returns: Reservation[] (always an array)
+
+// 지난 예약
+const past = await client.reservation.past(10);
+// Returns: Reservation[] (always an array)
+
+// 예약 상세
+const reservation = await client.reservation.get('RES-20260115-001');
+// Returns: Reservation
+
+// 예약 취소
+const cancelled = await client.reservation.cancel('RES-20260115-001', '일정 변경');
+// Returns: Reservation
 ```
 
 ### Auth (인증)
@@ -280,8 +404,8 @@ const response = await client.auth.socialCallback('google', code);
 
 ```typescript
 // 폼 목록
-const forms = await client.forms.list();
-// Returns: Form[]
+const { data: forms } = await client.forms.list();
+// Returns: ListResponse<Form>
 
 // 폼 상세
 const form = await client.forms.get('contact');
@@ -293,6 +417,10 @@ await client.forms.submit('contact', {
   email: 'user@example.com',
   message: '문의 내용',
 });
+
+// 내 제출 목록 (로그인 필요)
+const { data: submissions } = await client.forms.mySubmissions();
+// Returns: ListResponse<FormSubmission>
 ```
 
 ### Media (미디어) - Protected
@@ -307,12 +435,12 @@ const mediaList = await client.media.uploadMultiple([file1, file2]);
 // Returns: Media[]
 
 // 내 미디어 목록
-const mediaList = await client.media.list({
+const { data: mediaList, meta } = await client.media.list({
   page: 1,
   per_page: 20,
   type: 'image/jpeg', // optional
 });
-// Returns: { data: Media[], meta: {...} }
+// Returns: ListResponse<Media>
 
 // 미디어 삭제
 await client.media.delete(mediaId);
@@ -327,22 +455,22 @@ AI가 MCP를 통해 생성한 커스텀 데이터 구조에 접근합니다.
 ```typescript
 // 엔티티 목록 조회
 const entities = await client.entities.list();
-// Returns: CustomEntity[]
+// Returns: CustomEntity[] (always an array)
 
 // 엔티티 스키마 조회
 const schema = await client.entities.getSchema('customer');
 // Returns: EntitySchema
 
 // 레코드 목록 조회
-const customers = await client.entities.listRecords('customer', {
+const { data: customers, meta } = await client.entities.listRecords('customer', {
   page: 1,
   per_page: 20,
   status: 'active',
 });
-// Returns: { data: EntityRecord[], meta: {...} }
+// Returns: ListResponse<EntityRecord>
 
 // 데이터 필드로 필터링
-const vipCustomers = await client.entities.listRecords('customer', {
+const { data: vipCustomers } = await client.entities.listRecords('customer', {
   'data.tier': 'vip',
 });
 
@@ -415,6 +543,27 @@ const settings = await client.getSettings();
 
 ## Types
 
+### Common Types
+
+```typescript
+// Unified list response type
+interface ListResponse<T> {
+  data: T[];
+  meta: PaginationMeta;
+}
+
+interface PaginationMeta {
+  current_page: number;
+  last_page: number;
+  per_page: number;
+  total: number;
+  from: number | null;
+  to: number | null;
+}
+```
+
+### Resource Types
+
 ```typescript
 interface Board {
   id: number;
@@ -440,16 +589,6 @@ interface BoardPost {
   created_at: string;
 }
 
-interface BoardComment {
-  id: number;
-  post_id: number;
-  member?: Member;
-  parent_id?: number;
-  content: string;
-  replies?: BoardComment[];
-  created_at: string;
-}
-
 interface BlogPost {
   id: number;
   slug: string;
@@ -463,8 +602,6 @@ interface BlogPost {
   is_published: boolean;
   published_at?: string;
   view_count: number;
-  seo_title?: string;
-  seo_description?: string;
   created_at: string;
 }
 
@@ -473,38 +610,60 @@ interface Product {
   slug: string;
   name: string;
   description?: string;
-  content?: string;
   price: number;
   compare_price?: number;
   thumbnail?: string;
   images?: string[];
   status: 'draft' | 'active' | 'inactive';
   is_featured: boolean;
-  has_options: boolean;
-  variants?: ProductVariant[];
   in_stock?: boolean;
   discount_percent?: number;
   created_at: string;
 }
 
-interface Cart {
+interface Reservation {
   id: number;
-  items: CartItem[];
-  total: number;
-  total_quantity: number;
-  item_count: number;
+  reservation_number: string;
+  status: 'pending' | 'confirmed' | 'completed' | 'cancelled' | 'no_show';
+  status_label: string;
+  reservation_date: string;
+  start_time: string;
+  end_time: string;
+  time_range: string;
+  customer_name: string;
+  customer_phone: string | null;
+  customer_email: string | null;
+  price: number;
+  deposit: number;
+  payment_status: 'pending' | 'paid' | 'refunded' | 'partial';
+  can_cancel: boolean;
+  service: { id: number; name: string; duration: number; } | null;
+  staff: { id: number; name: string; avatar: string | null; } | null;
+  created_at: string;
 }
 
-interface Order {
+interface ReservationService {
   id: number;
-  order_number: string;
-  status: 'pending' | 'paid' | 'preparing' | 'shipping' | 'delivered' | 'cancelled';
-  subtotal: number;
-  discount_amount: number;
-  shipping_fee: number;
-  total: number;
-  items?: OrderItem[];
-  created_at: string;
+  name: string;
+  slug: string;
+  description: string | null;
+  thumbnail: string | null;
+  duration: number;
+  price: number;
+  requires_staff: boolean;
+  requires_payment: boolean;
+  deposit: number;
+  staffs: Array<{ id: number; name: string; avatar: string | null; }>;
+}
+
+interface ReservationSettings {
+  timezone: string;
+  slot_interval: number;
+  min_notice_hours: number;
+  max_advance_days: number;
+  cancellation_hours: number;
+  allow_online_payment: boolean;
+  bookable_date_range: { start: string; end: string; };
 }
 
 interface Member {
@@ -517,56 +676,16 @@ interface Member {
   created_at: string;
 }
 
-interface Form {
-  id: number;
-  slug: string;
-  name: string;
-  description?: string;
-  fields: FormField[];
-  settings: FormSettings;
-  is_active: boolean;
-}
-
-interface Media {
-  id: number;
-  url: string;
-  thumbnail_url?: string;
-  filename: string;
-  mime_type: string;
-  size: number;
-  created_at: string;
-}
-
 interface CustomEntity {
   id: number;
   name: string;
   slug: string;
   description?: string;
   schema: EntitySchema;
-  icon?: string;
   is_active: boolean;
-  records_count?: number;
   created_at: string;
 }
 
-interface EntitySchema {
-  fields: EntityField[];
-  display?: {
-    title_field?: string;
-    list_fields?: string;
-  };
-}
-
-interface EntityField {
-  name: string;
-  label: string;
-  type: 'text' | 'textarea' | 'number' | 'email' | 'url' | 'date' | 'datetime' | 'boolean' | 'select' | 'multiselect';
-  required?: boolean;
-  searchable?: boolean;
-  default?: any;
-  options?: Array<{ value: string; label: string }>;
-}
-
 interface EntityRecord {
   id: number;
   entity_id: number;
@@ -580,7 +699,7 @@ interface EntityRecord {
 ## Error Handling
 
 ```typescript
-import { Promptly, PromptlyError } from '@webbyon/promptly-sdk';
+import { Promptly, PromptlyError } from '@back23/promptly-sdk';
 
 try {
   await client.auth.login({ email: 'wrong@email.com', password: 'wrong' });
@@ -597,107 +716,106 @@ try {
 
 ```tsx
 import { useState, useEffect } from 'react';
-import { Promptly } from '@webbyon/promptly-sdk';
+import { Promptly } from '@back23/promptly-sdk';
 
 const client = new Promptly({
   tenantId: 'demo',
   baseUrl: 'https://promptly.webbyon.com',
 });
 
-// 게시판 글 목록
-function BoardPosts({ boardSlug }) {
+// 블로그 글 목록 (with pagination)
+function BlogList() {
   const [posts, setPosts] = useState([]);
-  const [loading, setLoading] = useState(true);
+  const [meta, setMeta] = useState(null);
+  const [page, setPage] = useState(1);
 
   useEffect(() => {
-    client.boards.listPosts(boardSlug)
-      .then(res => setPosts(res.data))
-      .finally(() => setLoading(false));
-  }, [boardSlug]);
-
-  if (loading) return <div>Loading...</div>;
+    client.blog.list({ page, per_page: 10 })
+      .then(({ data, meta }) => {
+        setPosts(data);  // Always an array
+        setMeta(meta);
+      });
+  }, [page]);
 
   return (
-    <table>
-      <thead>
-        <tr>
-          <th>제목</th>
-          <th>작성자</th>
-          <th>조회수</th>
-          <th>작성일</th>
-        </tr>
-      </thead>
-      <tbody>
-        {posts.map(post => (
-          <tr key={post.id}>
-            <td>{post.title}</td>
-            <td>{post.author}</td>
-            <td>{post.views}</td>
-            <td>{new Date(post.created_at).toLocaleDateString()}</td>
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
-
-// 로그인 폼
-function LoginForm() {
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-  const [error, setError] = useState('');
-
-  const handleSubmit = async (e) => {
-    e.preventDefault();
-    try {
-      await client.auth.login({ email, password });
-      // 로그인 성공 - 리다이렉트 등
-    } catch (err) {
-      setError(err.message);
-    }
-  };
+    <div>
+      {posts.map(post => (
+        <article key={post.id}>
+          <h2>{post.title}</h2>
+          <p>{post.excerpt}</p>
+        </article>
+      ))}
 
-  return (
-    <form onSubmit={handleSubmit}>
-      <input
-        type="email"
-        value={email}
-        onChange={e => setEmail(e.target.value)}
-        placeholder="이메일"
-      />
-      <input
-        type="password"
-        value={password}
-        onChange={e => setPassword(e.target.value)}
-        placeholder="비밀번호"
-      />
-      {error && <p style={{color: 'red'}}>{error}</p>}
-      <button type="submit">로그인</button>
-    </form>
+      {meta && (
+        <div>
+          Page {meta.current_page} of {meta.last_page}
+          <button
+            onClick={() => setPage(p => p - 1)}
+            disabled={page <= 1}
+          >
+            Previous
+          </button>
+          <button
+            onClick={() => setPage(p => p + 1)}
+            disabled={page >= meta.last_page}
+          >
+            Next
+          </button>
+        </div>
+      )}
+    </div>
   );
 }
 
-// 상품 목록
-function ProductList() {
-  const [products, setProducts] = useState([]);
+// 예약 폼
+function ReservationForm() {
+  const [services, setServices] = useState([]);
+  const [selectedService, setSelectedService] = useState(null);
+  const [dates, setDates] = useState([]);
+  const [slots, setSlots] = useState([]);
 
   useEffect(() => {
-    client.shop.listProducts({ is_featured: true })
-      .then(res => setProducts(res.data));
+    client.reservation.listServices().then(setServices);
   }, []);
 
+  useEffect(() => {
+    if (selectedService) {
+      client.reservation.getAvailableDates({
+        service_id: selectedService,
+      }).then(setDates);
+    }
+  }, [selectedService]);
+
+  const handleDateSelect = async (date) => {
+    const availableSlots = await client.reservation.getAvailableSlots({
+      service_id: selectedService,
+      date,
+    });
+    setSlots(availableSlots);
+  };
+
   return (
-    <div className="grid grid-cols-4 gap-4">
-      {products.map(product => (
-        <div key={product.id} className="border p-4">
-          <img src={product.thumbnail} alt={product.name} />
-          <h3>{product.name}</h3>
-          <p>{product.price.toLocaleString()}원</p>
-          {product.compare_price && (
-            <p className="line-through">{product.compare_price.toLocaleString()}원</p>
-          )}
-        </div>
-      ))}
+    <div>
+      <select onChange={e => setSelectedService(Number(e.target.value))}>
+        <option>서비스 선택</option>
+        {services.map(s => (
+          <option key={s.id} value={s.id}>{s.name}</option>
+        ))}
+      </select>
+
+      <div>
+        {dates.map(date => (
+          <button key={date} onClick={() => handleDateSelect(date)}>
+            {date}
+          </button>
+        ))}
+      </div>
+
+      <div>
+        {slots.filter(s => s.available).map(slot => (
+          <button key={slot.time}>{slot.time}</button>
+        ))}
+      </div>
     </div>
   );
 }

package/package.json

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