메인 콘텐츠로 건너뛰기

TypeScript SDK

공식 TypeScript SDK는 Headless Commerce API를 위한 완전한 타입 지원 클라이언트를 제공합니다.

설치

npm install @headless-commerce/sdk

빠른 시작

import { HeadlessCommerce } from '@headless-commerce/sdk';

// Admin 클라이언트 (서버 사이드)
const admin = new HeadlessCommerce({
  secretKey: 'sk_test_your_key',
});

// Storefront 클라이언트 (클라이언트 사이드 안전)
const storefront = new HeadlessCommerce({
  publishableKey: 'pk_test_your_key',
});

사용 예시

상품 목록 조회

const { data, has_more } = await storefront.products.list({
  status: 'active',
  limit: 20,
});
// data: Product[] — 자동완성이 지원되는 완전한 타입

장바구니 흐름

// 장바구니 생성
const cart = await storefront.carts.create({
  session_id: 'guest-session-123',
});

// 상품 추가
await storefront.carts.addItem(cart.id, {
  variant_id: 'var_001',
  quantity: 2,
});

// 계산된 합계와 함께 장바구니 조회
const updated = await storefront.carts.get(cart.id);
console.log(updated.summary.total);
// { amount: 78000, currency: "KRW" }

// 체크아웃
const order = await storefront.carts.checkout(cart.id, {
  email: 'customer@example.com',
  payment_provider: 'stripe',
  payment_method_id: 'pm_xxx',
});

Admin 작업

// 변형이 포함된 상품 생성
const product = await admin.products.create({
  name: 'Classic T-Shirt',
  type: 'physical',
  status: 'draft',
  options: [
    { name: 'Size', values: ['S', 'M', 'L'] },
    { name: 'Color', values: ['Black', 'White'] },
  ],
});

// 자동 페이지네이션
for await (const order of admin.orders.listAll({ status: 'confirmed' })) {
  console.log(order.number);
}

설정

옵션타입필수설명
secretKeystring*서버 사이드용 Secret API 키
publishableKeystring*클라이언트 사이드용 Publishable 키
baseUrlstring아니오커스텀 API Base URL (기본: https://api.headlesscommerce.io/v1)
secretKey 또는 publishableKey 중 하나가 필수입니다.