@01.software/sdk 0.1.0-dev.260119.0a66443 → 0.1.0-dev.260210.4ecca43

package/README.md

@@ -1,59 +1,42 @@
 # @01.software/sdk
 
-01.software 플랫폼의 공식 TypeScript SDK입니다. Supabase 스타일의 직관적인 API와 강력한 타입 안전성을 제공하며, 브라우저와 서버 환경을 모두 지원합니다.
+Official TypeScript SDK for the 01.software platform.
 
-## 주요 기능
-
-- 🔒 **타입 안전성**: TypeScript 기반의 완전한 타입 추론 및 discriminated union
-- 🌐 **멀티 환경**: 브라우저와 서버 환경 모두 지원
-- 🎯 **직관적 API**: Supabase 스타일의 쿼리 빌더
-- ⚡ **React Query 통합**: 데이터 페칭 및 캐싱 최적화
-- 🔄 **Webhook 처리**: 타입 안전한 webhook 핸들링
-- 📦 **37개 컬렉션**: 브랜드, 상품, 주문, 콘텐츠 등 포괄적 지원
-- 🔁 **자동 재시도**: Exponential backoff 전략 기반 재시도 로직
-- 🐛 **디버그 모드**: 요청/응답/에러 선택적 로깅
-- ⚠️ **향상된 에러 처리**: 사용자 친화적 에러 메시지 및 제안
-
-## 설치
+## Installation
 
 ```bash
 npm install @01.software/sdk
-# 또는
-yarn add @01.software/sdk
-# 또는
+# or
 pnpm add @01.software/sdk
 ```
 
-## 빠른 시작
+## Features
+
+- Full TypeScript type inference
+- Browser and server environment support
+- React Query integration
+- Automatic retry with exponential backoff
+- Webhook handling
 
-### 브라우저 환경
+## Getting Started
+
+### Browser Client
 
 ```typescript
 import { createBrowserClient } from '@01.software/sdk'
 
 const client = createBrowserClient({
-  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY
+  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
 })
 
-// 쿼리 빌더로 데이터 조회
-const { data: products } = await client.from('products').find({
+// Query data
+const { data } = await client.from('products').find({
   limit: 10,
-  where: { status: { equals: 'published' } }
+  where: { status: { equals: 'published' } },
 })
-
-// React Query 훅 사용
-function ProductList() {
-  const { data, isLoading } = client.query.useQuery({
-    collection: 'products',
-    options: { limit: 10 }
-  })
-
-  if (isLoading) return <div>Loading...</div>
-  return <div>{data?.map(p => p.name)}</div>
-}
 ```
 
-### 서버 환경
+### Server Client
 
 ```typescript
 import { createServerClient } from '@01.software/sdk'
@@ -63,476 +46,240 @@ const client = createServerClient({
   secretKey: process.env.SOFTWARE_SECRET_KEY,
 })
 
-// 주문 생성
+// Create order (server only)
 const order = await client.api.createOrder({
   paymentId: 'pay_123',
   orderNumber: generateOrderNumber(),
   email: 'user@example.com',
-  orderProducts: [
-    {
-      product: 'product_id',
-      variant: 'variant_id',
-      quantity: 1,
-      price: 10000,
-    },
-  ],
+  orderProducts: [...],
   totalAmount: 10000,
 })
 ```
 
-## 핵심 개념
-
-### 1. 클라이언트
+## API
 
-#### BrowserClient
-
-브라우저 환경에서 사용하는 클라이언트로, React Query 통합과 쿼리 빌더를 제공합니다.
+### Client Configuration
 
 ```typescript
 const client = createBrowserClient({
-  clientKey: 'your-client-key',
-  baseUrl: 'https://api.example.com', // 선택사항
-  debug: true, // 디버그 모드 활성화
-  retry: {
-    maxRetries: 3, // 최대 재시도 횟수
-    retryDelay: (attempt) => Math.min(1000 * 2 ** attempt, 10000), // Exponential backoff
-  },
-  errorLogger: {
-    log: (error) => console.error('SDK Error:', error), // 커스텀 에러 로거
-  },
+  clientKey: string,           // Required
+  baseUrl?: string,            // API URL (optional)
+  debug?: boolean | DebugOptions,
+  retry?: RetryOptions,
+  errorLogger?: ErrorLogger,
 })
 ```
 
-**주요 속성:**
-
-- `query`: React Query 훅 (`useQuery`, `useSuspenseQuery`, `useQueryById`, `useInfiniteQuery`)
-- `collections`: 컬렉션 API 클라이언트
-- `from()`: Supabase 스타일 쿼리 빌더
+| Option      | Type                      | Description                  |
+| ----------- | ------------------------- | ---------------------------- |
+| `clientKey` | `string`                  | API client key               |
+| `secretKey` | `string`                  | API secret key (server only) |
+| `baseUrl`   | `string`                  | API base URL                 |
+| `debug`     | `boolean \| DebugOptions` | Enable debug logging         |
+| `retry`     | `RetryOptions`            | Retry configuration          |
 
-#### ServerClient
+### Query Builder
 
-서버 환경에서 사용하는 클라이언트로, API 클라이언트를 추가로 제공합니다.
+Access collections via `client.from(collection)` method.
 
 ```typescript
-const client = createServerClient({
-  clientKey: 'your-client-key',
-  secretKey: 'your-secret-key', // 서버 전용
-})
-```
-
-**추가 속성:**
-
-- `api`: 주문 및 트랜잭션 API (`createOrder`, `updateOrder`, `updateTransaction`)
-
-### 2. 쿼리 빌더
-
-Supabase 스타일의 타입 안전한 쿼리 빌더를 제공합니다.
-
-```typescript
-// 목록 조회
+// List query
 const { data } = await client.from('products').find({
   limit: 20,
   page: 1,
   sort: '-createdAt',
-  where: {
-    status: { equals: 'published' },
-    price: { greater_than: 1000 },
-  },
+  where: { status: { equals: 'published' } },
 })
 
-// ID로 조회
-const { data: product } = await client.from('products').findById('product_id')
+// Single item query
+const { data } = await client.from('products').findById('id')
 
-// 생성
-const { data: newProduct } = await client.from('products').create({
-  name: '새 상품',
-  price: 10000,
-})
+// Create (server only)
+const { data } = await client.from('products').create({ name: 'Product' })
 
-// 수정
-const { data: updatedProduct } = await client
-  .from('products')
-  .update('product_id', {
-    name: '수정된 상품명',
-  })
+// Update (server only)
+const { data } = await client.from('products').update('id', { name: 'Updated' })
 
-// 삭제
-await client.from('products').remove('product_id')
+// Delete (server only)
+await client.from('products').remove('id')
 ```
 
-### 3. React Query 훅
+### API Response Structure
 
-데이터 페칭과 캐싱을 위한 React Query 통합을 제공합니다.
+All SDK methods return a standardized response format:
 
 ```typescript
-// 컬렉션 목록 조회
-const { data, isLoading, error, refetch } = client.query.useQuery({
+// Success Response
+interface ApiSuccessResponse<T> {
+  data: T                    // Actual data
+  success: true
+  message?: string           // Optional message from server
+  pagination?: PaginationMeta // For list queries
+}
+
+// Error Response
+interface ApiErrorResponse {
+  data: null
+  success: false
+  error: {
+    code: string
+    message: string
+    details?: unknown
+  }
+}
+```
+
+**Payload CMS API Mapping:**
+
+| Operation | Payload Response | SDK Response |
+|-----------|-----------------|--------------|
+| `find()` | `{docs: [], totalDocs, ...}` | `{data: [], success: true, pagination: {...}}` |
+| `findById()` | `{...document}` | `{data: {...}, success: true}` |
+| `create()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
+| `update()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
+| `remove()` | `{doc: {...}, message}` | `{data: {...}, success: true, message}` |
+
+### React Query Hooks
+
+```typescript
+// List query
+const { data, isLoading } = client.query.useQuery({
   collection: 'products',
-  options: {
-    limit: 10,
-    where: { status: { equals: 'published' } },
-  },
+  options: { limit: 10 },
 })
 
-// Suspense 모드 (서버 컴포넌트에서 사용)
+// Suspense mode
 const { data } = client.query.useSuspenseQuery({
   collection: 'products',
   options: { limit: 10 },
 })
 
-// 단일 항목 조회 (ID 기반)
-const { data: product } = client.query.useQueryById({
+// Query by ID
+const { data } = client.query.useQueryById({
   collection: 'products',
   id: 'product_id',
 })
 
-// 무한 스크롤
+// Infinite scroll
 const { data, fetchNextPage, hasNextPage } = client.query.useInfiniteQuery({
   collection: 'products',
   options: { limit: 20 },
 })
 ```
 
-### 4. Webhook 처리
+### Server API
 
-Next.js API Route에서 타입 안전한 webhook 처리를 제공합니다.
+Available only in ServerClient.
 
 ```typescript
-// app/api/webhook/route.ts
-import { handleWebhook } from '@01.software/sdk'
+// Create order
+await client.api.createOrder(data)
 
-export async function POST(request: Request) {
-  return handleWebhook(request, async (event) => {
-    console.log('Collection:', event.collection)
-    console.log('Operation:', event.operation) // 'create' | 'update' | 'delete'
-    console.log('Data:', event.data)
-
-    if (event.collection === 'orders') {
-      // 주문 관련 처리
-      if (event.operation === 'update') {
-        console.log('Order updated:', event.data.id)
-      }
-    }
-  })
-}
+// Update order
+await client.api.updateOrder(id, data)
+
+// Update transaction
+await client.api.updateTransaction(id, data)
 ```
 
-타입 안전한 컬렉션별 핸들러:
+### Webhook
 
 ```typescript
-import { createTypedWebhookHandler } from '@01.software/sdk'
-
-const handleOrderWebhook = createTypedWebhookHandler(
-  'orders',
-  async (event) => {
-    // event.data의 타입이 Order로 자동 추론됨
-    console.log('Order:', event.data.orderNumber)
-  },
-)
+import { handleWebhook, createTypedWebhookHandler } from '@01.software/sdk'
 
+// Basic handler
 export async function POST(request: Request) {
-  return handleWebhook(request, handleOrderWebhook)
+  return handleWebhook(request, async (event) => {
+    console.log(event.collection, event.operation, event.data)
+  })
 }
-```
-
-## API 레퍼런스
-
-### 컬렉션 목록
-
-SDK는 37개의 컬렉션을 지원합니다:
-
-**브랜드 관련**
-
-- `brands`, `brand-logos`, `brand-og-images`, `brand-settings`, `brand-secret-keys`
 
-**상품 관련**
-
-- `products`, `product-variants`, `product-options`, `product-categories`, `product-tags`, `product-images`
-
-**주문 관련**
-
-- `orders`, `order-products`, `returns`, `return-products`, `transactions`
-
-**콘텐츠 관련**
-
-- `posts`, `post-categories`, `post-tags`, `post-images`
-- `documents`, `document-images`
-- `entities`, `entity-categories`, `entity-tags`, `entity-images`
-
-**미디어 관련**
-
-- `playlists`, `playlist-images`, `musics`
-- `galleries`, `gallery-images`
-
-**기타**
+// Type-safe handler
+const handler = createTypedWebhookHandler('orders', async (event) => {
+  // event.data is typed as Order
+  console.log(event.data.orderNumber)
+})
+```
 
-- `links`, `link-images`, `nodes`, `forms`
+## Supported Collections
 
-### 유틸리티 함수
+| Category | Collections                                                                                                                        |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Tenant   | `tenants`, `tenant-metadata`, `tenant-logos`, `tenant-og-images`                                                                   |
+| Products | `products`, `product-variants`, `product-options`, `product-categories`, `product-tags`, `product-images`, `brands`, `brand-logos` |
+| Orders   | `orders`, `order-products`, `returns`, `return-products`, `transactions`                                                           |
+| Content  | `posts`, `post-categories`, `post-tags`, `post-images`, `documents`, `document-categories`, `document-images`                      |
+| Media    | `playlists`, `playlist-images`, `musics`, `galleries`, `gallery-images`, `media`                                                   |
 
-#### generateOrderNumber()
+## Utilities
 
-날짜 기반 주문 번호를 생성합니다.
+### generateOrderNumber
 
 ```typescript
 import { generateOrderNumber } from '@01.software/sdk'
 
 const orderNumber = generateOrderNumber()
-// 예: "260107123456" (YYMMDDRRRRRR 형식)
+// "260121123456" (YYMMDDRRRRRR format)
 ```
 
-#### formatOrderName()
-
-상품 옵션 배열을 주문명으로 포맷팅합니다.
+### formatOrderName
 
 ```typescript
 import { formatOrderName } from '@01.software/sdk'
 
-const orderName = formatOrderName([
-  { product: { name: '상품 A' }, variant: { name: '옵션 1' } },
-])
-// "상품 A"
+formatOrderName([{ product: { name: 'Product A' } }])
+// "Product A"
 
-const orderName2 = formatOrderName([
-  { product: { name: '상품 A' }, variant: { name: '옵션 1' } },
-  { product: { name: '상품 B' }, variant: { name: '옵션 2' } },
+formatOrderName([
+  { product: { name: 'Product A' } },
+  { product: { name: 'Product B' } },
 ])
-// "상품 A 외 1건"
+// "Product A and 1 more"
 ```
 
-### React 컴포넌트
+### RichTextContent
 
-#### RichTextContent
+React component for rendering Payload CMS Lexical rich text.
 
-Payload CMS의 Lexical 리치 텍스트를 렌더링합니다.
-
-```typescript
+```tsx
 import { RichTextContent } from '@01.software/sdk'
 
-function Article({ content }) {
-  return (
-    <RichTextContent
-      data={content}
-      className="prose"
-      internalDocToHref={(args) => `/posts/${args.doc.slug}`}
-      blocks={{
-        Iframe: ({ url }) => <iframe src={url} />,
-        Player: ({ videoId }) => <VideoPlayer id={videoId} />
-      }}
-    />
-  )
-}
-```
-
-## 고급 사용법
-
-### 디버그 모드
-
-개발 중 요청/응답을 로깅하여 디버깅을 쉽게 할 수 있습니다.
-
-```typescript
-// 전체 디버그 모드
-const client = createBrowserClient({
-  clientKey: 'your-key',
-  debug: true, // 모든 요청/응답/에러 로깅
-})
-
-// 선택적 디버그 모드
-const client = createBrowserClient({
-  clientKey: 'your-key',
-  debug: {
-    logRequests: true, // 요청만 로깅
-    logResponses: false, // 응답 로깅 안 함
-    logErrors: true, // 에러만 로깅
-  },
-})
+;<RichTextContent
+  data={content}
+  className="prose"
+  internalDocToHref={(args) => `/posts/${args.doc.slug}`}
+  blocks={{
+    Iframe: ({ url }) => <iframe src={url} />,
+    Player: ({ videoId }) => <VideoPlayer id={videoId} />,
+  }}
+/>
 ```
 
-### 재시도 로직
-
-네트워크 오류나 서버 에러 시 자동으로 재시도합니다.
-
-```typescript
-const client = createBrowserClient({
-  clientKey: 'your-key',
-  retry: {
-    maxRetries: 3, // 최대 재시도 횟수 (기본값: 3)
-    retryableStatuses: [408, 429, 500, 502, 503, 504], // 재시도할 HTTP 상태 코드
-    retryDelay: (attempt) => {
-      // Exponential backoff: 1초 → 2초 → 4초 → 8초 (최대 10초)
-      return Math.min(1000 * 2 ** attempt, 10000)
-    },
-  },
-})
-```
-
-**기본 동작:**
-
-- 네트워크 에러는 항상 재시도
-- 408, 429, 500, 502, 503, 504 상태 코드는 재시도
-- 401, 404 등 클라이언트 에러는 재시도하지 않음
-- Exponential backoff 전략 사용
-
-### 쿼리 옵션
-
-```typescript
-// 정렬
-const { data } = await client.from('products').find({
-  sort: '-createdAt', // 내림차순
-})
-
-// 페이지네이션
-const { data, pagination } = await client.from('products').find({
-  page: 2,
-  limit: 20,
-})
-console.log(pagination.hasNextPage)
-
-// 복잡한 필터
-const { data } = await client.from('products').find({
-  where: {
-    and: [
-      { status: { equals: 'published' } },
-      { price: { greater_than: 1000, less_than: 50000 } },
-      {
-        or: [
-          { category: { equals: 'electronics' } },
-          { tags: { contains: 'featured' } },
-        ],
-      },
-    ],
-  },
-})
-```
-
-### React Query 옵션
-
-```typescript
-const { data } = client.query.useQuery(
-  {
-    collection: 'products',
-    options: { limit: 10 },
-  },
-  {
-    staleTime: 5 * 60 * 1000, // 5분
-    gcTime: 10 * 60 * 1000, // 10분 (React Query v5에서 cacheTime → gcTime)
-    refetchOnWindowFocus: false,
-  },
-)
-```
-
-### 에러 처리
-
-SDK는 사용자 친화적인 에러 메시지와 제안을 제공합니다.
+## Error Handling
 
 ```typescript
 import {
-  SDKError,
-  ApiError,
-  NetworkError,
-  ValidationError,
-  TimeoutError,
   isNetworkError,
+  isSuccessResponse,
+  isErrorResponse,
 } from '@01.software/sdk'
 
-try {
-  const { data } = await client.from('products').find()
-} catch (error) {
-  if (isNetworkError(error)) {
-    // 사용자 친화적 메시지
-    console.error(error.getUserMessage())
-    // "네트워크 연결을 확인해주세요."
-
-    // 개발자용 메시지
-    console.error(error.message)
-
-    // 해결 제안
-    console.log(error.suggestion)
-    // "인터넷 연결을 확인하거나 잠시 후 다시 시도해주세요."
-  }
-}
-```
-
-#### 타입 안전한 응답 처리
-
-```typescript
-import { isSuccessResponse, isErrorResponse } from '@01.software/sdk'
-
 const response = await client.from('products').find()
 
 if (isSuccessResponse(response)) {
-  // TypeScript가 response.data의 타입을 Product[]로 추론
   console.log(response.data)
-  console.log(response.pagination)
 } else if (isErrorResponse(response)) {
-  // TypeScript가 response.error의 타입을 추론
-  console.error(response.error.code)
   console.error(response.error.message)
 }
 ```
 
-## 보안
+Error classes: `SDKError`, `ApiError`, `NetworkError`, `ValidationError`, `TimeoutError`
 
-### 환경 변수 설정
+## Environment Variables
 
 ```bash
-# .env.local
 NEXT_PUBLIC_SOFTWARE_CLIENT_KEY=your_client_key
-SOFTWARE_SECRET_KEY=your_secret_key # 서버 전용
-```
-
-### 주의사항
-
-- `clientKey`는 브라우저에 노출되어도 안전합니다.
-- `secretKey`는 **절대** 브라우저에 노출되어서는 안 됩니다.
-- `secretKey`는 서버 환경(API Route, Server Component 등)에서만 사용하세요.
-
-## 타입 시스템
-
-모든 컬렉션은 자동으로 타입이 추론됩니다:
-
-```typescript
-// 타입이 자동으로 추론됨
-const { data: products } = await client.from('products').find()
-// products의 타입: Product[]
-
-const { data: product } = await client.from('products').findById('id')
-// product의 타입: Product
-
-// 생성 시에도 타입 체크
-await client.from('products').create({
-  name: '상품명', // ✅ OK
-  price: 10000, // ✅ OK
-  invalid: 'field', // ❌ 타입 에러
-})
-```
-
-## 개발
-
-SDK는 포괄적인 테스트를 포함하고 있으며, 타입 안전성과 사용자 경험을 최우선으로 설계되었습니다.
-
-### 테스트
-
-```bash
-# 모든 테스트 실행
-pnpm test
-
-# watch 모드로 실행
-pnpm test:watch
+SOFTWARE_SECRET_KEY=your_secret_key  # Server only
 ```
 
-### 주요 특징
-
-- ✅ **완전한 타입 안전성**: TypeScript 기반 타입 추론
-- ✅ **사용자 친화적 에러 처리**: 명확한 에러 메시지와 해결 제안
-- ✅ **자동 재시도**: 네트워크 오류 시 exponential backoff 전략
-- ✅ **디버그 모드**: 개발 중 요청/응답/에러 로깅
-- ✅ **React Query 통합**: 효율적인 데이터 페칭 및 캐싱
-
-## 라이센스
-
-MIT
-
-## 지원
-
-문제가 발생하거나 궁금한 점이 있다면 이슈를 등록해주세요.
+> `secretKey` should only be used in server environments. Never expose it to the browser.