@01.software/sdk 0.0.1-260102065059 → 0.1.0-dev.260109.7cf07c9

package/README.md

@@ -0,0 +1,530 @@
+# @01.software/sdk
+
+01.software 플랫폼의 공식 TypeScript SDK입니다. Supabase 스타일의 직관적인 API와 강력한 타입 안전성을 제공하며, 브라우저와 서버 환경을 모두 지원합니다.
+
+## 주요 기능
+
+- 🔒 **타입 안전성**: TypeScript 기반의 완전한 타입 추론 및 discriminated union
+- 🌐 **멀티 환경**: 브라우저와 서버 환경 모두 지원
+- 🎯 **직관적 API**: Supabase 스타일의 쿼리 빌더
+- ⚡ **React Query 통합**: 데이터 페칭 및 캐싱 최적화
+- 🔄 **Webhook 처리**: 타입 안전한 webhook 핸들링
+- 📦 **37개 컬렉션**: 브랜드, 상품, 주문, 콘텐츠 등 포괄적 지원
+- 🔁 **자동 재시도**: Exponential backoff 전략 기반 재시도 로직
+- 🐛 **디버그 모드**: 요청/응답/에러 선택적 로깅
+- ⚠️ **향상된 에러 처리**: 사용자 친화적 에러 메시지 및 제안
+
+## 설치
+
+```bash
+npm install @01.software/sdk
+# 또는
+yarn add @01.software/sdk
+# 또는
+pnpm add @01.software/sdk
+```
+
+## 빠른 시작
+
+### 브라우저 환경
+
+```typescript
+import { createBrowserClient } from '@01.software/sdk'
+
+const client = createBrowserClient({
+  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY
+})
+
+// 쿼리 빌더로 데이터 조회
+const { data: products } = await client.from('products').find({
+  limit: 10,
+  where: { status: { equals: 'published' } }
+})
+
+// React Query 훅 사용
+function ProductList() {
+  const { data, isLoading } = client.query.useCollection('products', {
+    limit: 10
+  })
+
+  if (isLoading) return <div>Loading...</div>
+  return <div>{data?.docs.map(p => p.name)}</div>
+}
+```
+
+### 서버 환경
+
+```typescript
+import { createServerClient } from '@01.software/sdk'
+
+const client = createServerClient({
+  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY,
+  secretKey: process.env.SOFTWARE_SECRET_KEY,
+})
+
+// 주문 생성
+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,
+    },
+  ],
+  totalAmount: 10000,
+})
+```
+
+## 핵심 개념
+
+### 1. 클라이언트
+
+#### BrowserClient
+
+브라우저 환경에서 사용하는 클라이언트로, React Query 통합과 쿼리 빌더를 제공합니다.
+
+```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), // 커스텀 에러 로거
+  },
+})
+```
+
+**주요 속성:**
+
+- `query`: React Query 훅 (`useCollection`, `useCollectionSingle`, `useCollectionInfinite`)
+- `collections`: 컬렉션 API 클라이언트
+- `from()`: Supabase 스타일 쿼리 빌더
+
+#### ServerClient
+
+서버 환경에서 사용하는 클라이언트로, API 클라이언트를 추가로 제공합니다.
+
+```typescript
+const client = createServerClient({
+  clientKey: 'your-client-key',
+  secretKey: 'your-secret-key', // 서버 전용
+})
+```
+
+**추가 속성:**
+
+- `api`: 주문 및 트랜잭션 API (`createOrder`, `updateOrder`, `updateTransaction`)
+
+### 2. 쿼리 빌더
+
+Supabase 스타일의 타입 안전한 쿼리 빌더를 제공합니다.
+
+```typescript
+// 목록 조회
+const { data } = await client.from('products').find({
+  limit: 20,
+  page: 1,
+  sort: '-createdAt',
+  where: {
+    status: { equals: 'published' },
+    price: { greater_than: 1000 },
+  },
+})
+
+// ID로 조회
+const { data: product } = await client.from('products').findById('product_id')
+
+// 생성
+const { data: newProduct } = await client.from('products').create({
+  name: '새 상품',
+  price: 10000,
+})
+
+// 수정
+const { data: updatedProduct } = await client
+  .from('products')
+  .update('product_id', {
+    name: '수정된 상품명',
+  })
+
+// 삭제
+await client.from('products').remove('product_id')
+```
+
+### 3. React Query 훅
+
+데이터 페칭과 캐싱을 위한 React Query 통합을 제공합니다.
+
+```typescript
+// 컬렉션 목록 조회
+const { data, isLoading, error } = client.query.useCollection('products', {
+  limit: 10,
+  where: { status: { equals: 'published' } },
+})
+
+// 단일 항목 조회
+const { data: product } = client.query.useCollectionSingle('products', {
+  where: { slug: { equals: 'my-product' } },
+})
+
+// 무한 스크롤
+const { data, fetchNextPage, hasNextPage } = client.query.useCollectionInfinite(
+  'products',
+  {
+    limit: 20,
+  },
+)
+```
+
+### 4. Webhook 처리
+
+Next.js API Route에서 타입 안전한 webhook 처리를 제공합니다.
+
+```typescript
+// app/api/webhook/route.ts
+import { handleWebhook } from '@01.software/sdk'
+
+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)
+      }
+    }
+  })
+}
+```
+
+타입 안전한 컬렉션별 핸들러:
+
+```typescript
+import { createTypedWebhookHandler } from '@01.software/sdk'
+
+const handleOrderWebhook = createTypedWebhookHandler(
+  'orders',
+  async (event) => {
+    // event.data의 타입이 Order로 자동 추론됨
+    console.log('Order:', event.data.orderNumber)
+  },
+)
+
+export async function POST(request: Request) {
+  return handleWebhook(request, handleOrderWebhook)
+}
+```
+
+## 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`
+
+**기타**
+
+- `links`, `link-images`, `nodes`, `forms`
+
+### 유틸리티 함수
+
+#### generateOrderNumber()
+
+날짜 기반 주문 번호를 생성합니다.
+
+```typescript
+import { generateOrderNumber } from '@01.software/sdk'
+
+const orderNumber = generateOrderNumber()
+// 예: "260107123456" (YYMMDDRRRRRR 형식)
+```
+
+#### formatOrderName()
+
+상품 옵션 배열을 주문명으로 포맷팅합니다.
+
+```typescript
+import { formatOrderName } from '@01.software/sdk'
+
+const orderName = formatOrderName([
+  { product: { name: '상품 A' }, variant: { name: '옵션 1' } },
+])
+// "상품 A"
+
+const orderName2 = formatOrderName([
+  { product: { name: '상품 A' }, variant: { name: '옵션 1' } },
+  { product: { name: '상품 B' }, variant: { name: '옵션 2' } },
+])
+// "상품 A 외 1건"
+```
+
+### React 컴포넌트
+
+#### RichTextContent
+
+Payload CMS의 Lexical 리치 텍스트를 렌더링합니다.
+
+```typescript
+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, // 에러만 로깅
+  },
+})
+```
+
+### 재시도 로직
+
+네트워크 오류나 서버 에러 시 자동으로 재시도합니다.
+
+```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.useCollection(
+  'products',
+  {
+    limit: 10,
+  },
+  {
+    staleTime: 5 * 60 * 1000, // 5분
+    cacheTime: 10 * 60 * 1000, // 10분
+    refetchOnWindowFocus: false,
+    keepPreviousData: true,
+  },
+)
+```
+
+### 에러 처리
+
+SDK는 사용자 친화적인 에러 메시지와 제안을 제공합니다.
+
+```typescript
+import {
+  SDKError,
+  ApiError,
+  NetworkError,
+  ValidationError,
+  TimeoutError,
+  isNetworkError,
+} 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)
+}
+```
+
+## 보안
+
+### 환경 변수 설정
+
+```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
+```
+
+### 주요 특징
+
+- ✅ **완전한 타입 안전성**: TypeScript 기반 타입 추론
+- ✅ **사용자 친화적 에러 처리**: 명확한 에러 메시지와 해결 제안
+- ✅ **자동 재시도**: 네트워크 오류 시 exponential backoff 전략
+- ✅ **디버그 모드**: 개발 중 요청/응답/에러 로깅
+- ✅ **React Query 통합**: 효율적인 데이터 페칭 및 캐싱
+
+## 라이센스
+
+MIT
+
+## 지원
+
+문제가 발생하거나 궁금한 점이 있다면 이슈를 등록해주세요.