@sellosh/commerce — Sello 커머스 SDK

모든 스토어프론트(손코딩 스토어 · frontend-01 · sello.sh 에서 AI 가 생성하는 스토어)가 공유하는 타입드 클라이언트 + React 훅. 디자인·레이아웃은 자유롭게 만들되, 결제·재고·인증의 안전 경계는 이 SDK 가 한 곳에서 책임진다.

왜 SDK 먼저인가

이게 "계약(contract)"이다. 누가 어떤 레이아웃으로 스토어를 만들든 —

• 상품/장바구니/주문/결제/인증은 이 SDK 를 통해서만 백엔드(/api/frontend/*)에 닿는다.
• SDK 는 시크릿을 절대 갖지 않는다. 결제는 항상 서버 승인(confirmTossPayment → 서버가 buildOrder 로 가격·재고 재검증 + total === amount 확인 + 가게 시크릿키로 토스 승인)을 호출.
• 그래서 스토어 코드가 아무리 자유로워도(또는 AI 가 생성해도) 돈·데이터 무결성은 못 깨뜨린다.

구성

• @sellosh/commerce — 프레임워크 무관 코어: types, createSelloClient, resolveBusinessSlug, 순수 장바구니 로직(addToCart/cartTotal/cartToOrderItems…), checkout draft.
• @sellosh/commerce/react — SelloProvider + 훅(useAuth/useCart/useProducts/useProduct/ useOrders/useOrder/usePaymentConfig) + <TossPaymentWidget>.

빠른 사용

// 앱 루트
import { SelloProvider } from "@sellosh/commerce/react";

<SelloProvider apiBase="https://www.sello.sh" /* Next 면 businessSlug="myshop" 권장 */>
  <App />
</SelloProvider>;

// 상품 목록 (레이아웃은 자유)
import { useProducts, useCart } from "@sellosh/commerce/react";

function Shop() {
  const { products, loading } = useProducts();
  const cart = useCart();
  if (loading) return <Spinner />;
  return products.map((p) => (
    <MyProductCard
      key={p.id}
      product={p}
      onAdd={() =>
        cart.add({
          productId: p.id, name: p.name, image_url: p.image_url,
          options: {}, unitPrice: p.price, currency: p.currency,
          quantity: 1, maxStock: p.stock ?? null,
        })
      }
    />
  ));
}

// 결제 (안전 경계) — 위젯 렌더 → 토스 결제 → 성공 페이지에서 서버 승인
import { usePaymentConfig, useCart, TossPaymentWidget, useSello } from "@sellosh/commerce/react";
import { cartToOrderItems, saveDraft } from "@sellosh/commerce";

// 체크아웃
const { config } = usePaymentConfig();
const cart = useCart();
// ...config.tossClientKey 로 <TossPaymentWidget> 렌더, onReady(pay) 받아 결제 요청.
// successUrl 로 돌아오면:
const { client } = useSello();
await client.confirmTossPayment({
  paymentKey, orderId, amount,
  items: cartToOrderItems(cart.items),
  customer_name, phone, address,
  businessSlug, // 비회원이면 필수
});
// → 서버가 재검증 후 주문 생성. 클라가 보낸 가격/금액은 신뢰하지 않음.

멀티테넌트 / 환경

• 가게 식별: 서브도메인(myshop.sello.sh) → ?business= → fallbackSlug. Next 에선 businessSlug prop 권장.
• apiBase 는 prop 으로 주입(빌드툴 env 에 비의존) — Vite/Next/AI생성 스토어 동일하게 동작.

로드맵

• [ ] frontend-01 을 이 SDK 로 마이그레이션(중복 제거, 검증)
• [ ] npm 퍼블리시(@sellosh/commerce) — 별도 레포(chaae 등)에서 설치
• [ ] <CheckoutForm> / 주소검색 등 옵션 UI 프리미티브
• [ ] AI 스토어 생성기가 이 SDK 표면을 타겟으로 코드 생성