SDK Introduction

01.software SDK는 TypeScript로 작성된 공식 클라이언트 라이브러리입니다.

설치

npm install @01.software/sdk
# 또는
pnpm add @01.software/sdk

특징

타입 안전성

모든 컬렉션과 응답에 대해 완전한 TypeScript 타입을 제공합니다.

// 타입이 자동으로 추론됩니다
const response = await client.from('products').find()
// response: ApiResponse<Product[]>

if (response.success) {
  response.data  // Product[]
  response.pagination  // PaginationMeta
}

두 가지 클라이언트

클라이언트	용도	환경
`BrowserClient`	클라이언트 컴포넌트	브라우저
`ServerClient`	Server Component, API Route	Node.js

React Query 통합

데이터 페칭, 캐싱, 무효화를 위한 React 훅을 제공합니다.

// 목록 조회
const { data, isLoading } = client.query.useCollection('products')

// 단일 조회
const { data } = client.query.useById('products', id)

// 무한 스크롤
const { data, fetchNextPage } = client.query.useCollectionInfinite('products')

에러 처리

구조화된 에러 타입과 타입 가드를 제공합니다.

import { isNetworkError, isValidationError } from '@01.software/sdk'

try {
  const response = await client.from('products').find()
} catch (error) {
  if (isNetworkError(error)) {
    console.error('네트워크 오류:', error.getUserMessage())
  }
}

기본 사용법

Browser Client

import { createBrowserClient } from '@01.software/sdk'

// 클라이언트 생성
const client = createBrowserClient({
  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!
})

// 데이터 조회
const response = await client.from('products').find({
  where: { status: { equals: 'active' } },
  limit: 20
})

// React Query 훅 사용
const { data, isLoading } = client.query.useCollection('products')

Server Client

import { createServerClient } from '@01.software/sdk'

// 클라이언트 생성
const client = createServerClient({
  clientKey: process.env.NEXT_PUBLIC_SOFTWARE_CLIENT_KEY!,
  secretKey: process.env.SOFTWARE_SECRET_KEY!
})

// 데이터 조회
const response = await client.from('products').find()

// CRUD 작업
await client.from('products').create({ data: { ... } })
await client.from('products').update(id, { data: { ... } })
await client.from('products').remove(id)

// 주문 API
await client.api.createOrder({ ... })

응답 형식

성공 응답

interface ApiSuccessResponse<T> {
  success: true
  data: T
  message?: string
  pagination?: {
    page: number
    limit: number
    totalDocs: number
    totalPages: number
    hasNextPage: boolean
    hasPrevPage: boolean
  }
}

에러 응답

interface ApiErrorResponse {
  success: false
  data: null
  error: {
    code: string
    message: string
    details?: unknown
  }
}

응답 처리

import { isSuccessResponse, isErrorResponse } from '@01.software/sdk'

const response = await client.from('products').find()

if (isSuccessResponse(response)) {
  console.log(response.data)
  console.log(response.pagination?.totalDocs)
} else if (isErrorResponse(response)) {
  console.error(response.error.message)
}

Exports

SDK에서 내보내는 주요 항목:

// 클라이언트 생성
export { createBrowserClient, createServerClient }

// 타입
export type {
  ApiResponse,
  ApiSuccessResponse,
  ApiErrorResponse,
  PaginationMeta
}

// 타입 가드
export { isSuccessResponse, isErrorResponse }

// 에러 클래스
export {
  SDKError,
  NetworkError,
  ValidationError,
  ApiError,
  ConfigError,
  TimeoutError
}

// 에러 타입 가드
export {
  isSDKError,
  isNetworkError,
  isValidationError,
  isApiError,
  isConfigError,
  isTimeoutError
}

// Webhook
export { handleWebhook, createTypedWebhookHandler }

// 컴포넌트
export { RichTextContent }

// 유틸리티
export { generateOrderNumber, formatOrderName }

다음 단계

Client - 클라이언트 설정
Query Builder - 쿼리 작성
React Query - React 훅
Error Handling - 에러 처리

SDK Introduction

On this page