@sellosh/commerce 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# @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>`.
+
+## 빠른 사용
+
+```tsx
+// 앱 루트
+import { SelloProvider } from "@sellosh/commerce/react";
+
+<SelloProvider apiBase="https://www.sello.sh" /* Next 면 businessSlug="myshop" 권장 */>
+  <App />
+</SelloProvider>;
+```
+
+```tsx
+// 상품 목록 (레이아웃은 자유)
+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,
+        })
+      }
+    />
+  ));
+}
+```
+
+```tsx
+// 결제 (안전 경계) — 위젯 렌더 → 토스 결제 → 성공 페이지에서 서버 승인
+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 표면을 타겟으로 코드 생성

package/dist/business.d.ts

@@ -0,0 +1,7 @@
+export interface ResolveSlugOptions {
+    /** 서브도메인/쿼리로 못 찾을 때 쓸 기본 slug (env 값 등을 호출부에서 주입) */
+    fallback?: string | null;
+    /** 테넌트 서브도메인이 아닌 예약어 */
+    reserved?: string[];
+}
+export declare function resolveBusinessSlug(opts?: ResolveSlugOptions): string | null;

package/dist/business.js

@@ -0,0 +1,28 @@
+// 현재 화면이 "어느 가게(business)"인지 판별.
+// 우선순위: 서브도메인 → ?business= 쿼리 → fallback.
+// production 은 서브도메인: {slug}.sello.sh → slug. (*.vercel.app, bare localhost 는 제외)
+//
+// 빌드툴(import.meta / process.env)에 의존하지 않도록 fallback 을 인자로 받는다 —
+// Vite·Next·AI생성 스토어 어디서나 동일하게 쓰인다.
+const DEFAULT_RESERVED = ["www", "app", "admin", "api", "localhost"];
+export function resolveBusinessSlug(opts = {}) {
+    if (typeof window === "undefined")
+        return opts.fallback ?? null;
+    const host = window.location.hostname;
+    const parts = host.split(".");
+    let slug = null;
+    if (host.endsWith(".localhost") && parts.length >= 2) {
+        slug = parts[0] ?? null; // shopdemo.localhost
+    }
+    else if (parts.length > 2 && !host.endsWith(".vercel.app")) {
+        slug = parts[0] ?? null; // shopdemo.sello.sh
+    }
+    const reserved = new Set(opts.reserved ?? DEFAULT_RESERVED);
+    if (slug && reserved.has(slug))
+        slug = null;
+    if (!slug) {
+        const fromQuery = new URLSearchParams(window.location.search).get("business");
+        slug = fromQuery || opts.fallback || null;
+    }
+    return slug;
+}

package/dist/cart.d.ts

@@ -0,0 +1,11 @@
+import type { CartItem, CartItemInput } from "./types";
+/** (상품 + 옵션조합) 단위의 고유 키 — 같은 상품 다른 옵션은 별도 라인. */
+export declare function itemKey(productId: number, options: Record<string, string>): string;
+/** 동일 (상품+옵션)이면 수량 합산(재고 상한 적용), 아니면 새 라인 추가. */
+export declare function addToCart(items: CartItem[], item: CartItem): CartItem[];
+export declare function setCartQty(items: CartItem[], key: string, qty: number): CartItem[];
+export declare function removeFromCart(items: CartItem[], key: string): CartItem[];
+export declare function cartCount(items: CartItem[]): number;
+export declare function cartTotal(items: CartItem[]): number;
+/** 장바구니 → 서버 주문 아이템(가격·재고는 서버가 재검증). */
+export declare function cartToOrderItems(items: CartItem[]): CartItemInput[];

package/dist/cart.js

@@ -0,0 +1,51 @@
+/** (상품 + 옵션조합) 단위의 고유 키 — 같은 상품 다른 옵션은 별도 라인. */
+export function itemKey(productId, options) {
+    return (productId +
+        "::" +
+        Object.keys(options)
+            .sort()
+            .map((k) => `${k}=${options[k]}`)
+            .join("&"));
+}
+/** 동일 (상품+옵션)이면 수량 합산(재고 상한 적용), 아니면 새 라인 추가. */
+export function addToCart(items, item) {
+    const k = itemKey(item.productId, item.options);
+    const idx = items.findIndex((x) => itemKey(x.productId, x.options) === k);
+    if (idx >= 0) {
+        const next = [...items];
+        const cur = next[idx];
+        let qty = cur.quantity + item.quantity;
+        if (cur.maxStock != null)
+            qty = Math.min(qty, cur.maxStock);
+        next[idx] = { ...cur, quantity: qty };
+        return next;
+    }
+    return [...items, item];
+}
+export function setCartQty(items, key, qty) {
+    return items.map((x) => {
+        if (itemKey(x.productId, x.options) !== key)
+            return x;
+        let q = Math.max(1, qty);
+        if (x.maxStock != null)
+            q = Math.min(q, x.maxStock);
+        return { ...x, quantity: q };
+    });
+}
+export function removeFromCart(items, key) {
+    return items.filter((x) => itemKey(x.productId, x.options) !== key);
+}
+export function cartCount(items) {
+    return items.reduce((s, x) => s + x.quantity, 0);
+}
+export function cartTotal(items) {
+    return items.reduce((s, x) => s + x.unitPrice * x.quantity, 0);
+}
+/** 장바구니 → 서버 주문 아이템(가격·재고는 서버가 재검증). */
+export function cartToOrderItems(items) {
+    return items.map((x) => ({
+        product_id: x.productId,
+        options: x.options,
+        quantity: x.quantity,
+    }));
+}

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+import type { AuthProviders, AuthResult, AuthUser, CartItemInput, ConfirmTossInput, ConfirmTossResult, MetaConfig, Order, OrderWithItems, PaymentConfig, ProductDetailResult, ProductListResult, ProfileInput, ReviewListParams, ReviewListResult } from "./types";
+export interface SelloClientConfig {
+    /** API 베이스 URL. "" = 동일 출처(프록시/리라이트). 예: "https://www.sello.sh" */
+    apiBase?: string;
+    /** 기본 가게 slug — 메서드에 slug 를 안 넘기면 이걸 사용 */
+    businessSlug?: string | null;
+    /** 인증이 필요한 호출에 붙일 Bearer 토큰 공급자 */
+    getToken?: () => string | null | undefined;
+}
+export interface CreateOrderInput {
+    items: CartItemInput[];
+    customer_name: string;
+    phone: string;
+    address: string;
+}
+export interface SelloClient {
+    readonly businessSlug: string | null;
+    listProducts(slug?: string): Promise<ProductListResult>;
+    getProduct(id: number, slug?: string): Promise<ProductDetailResult>;
+    getPaymentConfig(slug?: string): Promise<PaymentConfig>;
+    confirmTossPayment(input: ConfirmTossInput): Promise<ConfirmTossResult>;
+    listOrders(): Promise<{
+        orders: Order[];
+    }>;
+    getOrder(id: number, opts?: {
+        guestToken?: string;
+    }): Promise<OrderWithItems>;
+    lookupOrder(input: {
+        businessSlug: string;
+        orderId: number | string;
+        phone: string;
+    }): Promise<OrderWithItems>;
+    claimOrder(id: number, guestToken: string): Promise<{
+        ok: true;
+        order: {
+            id: number;
+        };
+    }>;
+    createOrder(input: CreateOrderInput): Promise<{
+        order: {
+            id: number;
+            total: number;
+            status: string;
+        };
+    }>;
+    register(input: {
+        slug: string;
+        email: string;
+        password: string;
+        name?: string;
+    }): Promise<AuthResult>;
+    login(input: {
+        slug: string;
+        email: string;
+        password: string;
+    }): Promise<AuthResult>;
+    me(): Promise<{
+        user: AuthUser;
+    }>;
+    getProviders(slug?: string): Promise<AuthProviders>;
+    updateProfile(input: ProfileInput): Promise<{
+        user: AuthUser;
+    }>;
+    /** 소셜 로그인 시작 URL (브라우저를 이 URL 로 리다이렉트) */
+    oauthStartUrl(provider: "google" | "kakao", returnUrl: string, slug?: string): string;
+    listReviews(params: ReviewListParams): Promise<ReviewListResult>;
+    getMetaConfig(slug?: string): Promise<MetaConfig>;
+}
+export declare function createSelloClient(config?: SelloClientConfig): SelloClient;

package/dist/client.js

@@ -0,0 +1,74 @@
+export function createSelloClient(config = {}) {
+    const apiBase = config.apiBase ?? "";
+    const q = (s) => encodeURIComponent(s);
+    function requireSlug(slug) {
+        const s = slug ?? config.businessSlug ?? null;
+        if (!s) {
+            throw new Error("business slug 가 필요합니다 (SelloProvider 의 businessSlug 또는 인자로 전달).");
+        }
+        return s;
+    }
+    async function req(path, options = {}, withAuth = false) {
+        const headers = new Headers(options.headers);
+        if (options.body)
+            headers.set("Content-Type", "application/json");
+        if (withAuth) {
+            const token = config.getToken?.();
+            if (token)
+                headers.set("Authorization", `Bearer ${token}`);
+        }
+        const res = await fetch(`${apiBase}${path}`, { ...options, headers });
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            const msg = typeof data === "object" && data !== null && "error" in data
+                ? String(data.error)
+                : "요청에 실패했습니다.";
+            throw new Error(msg);
+        }
+        return data;
+    }
+    return {
+        get businessSlug() {
+            return config.businessSlug ?? null;
+        },
+        listProducts: (slug) => req(`/api/frontend/products?business=${q(requireSlug(slug))}`),
+        getProduct: (id, slug) => req(`/api/frontend/products/${id}?business=${q(requireSlug(slug))}`),
+        getPaymentConfig: (slug) => req(`/api/frontend/payments/config?business=${q(requireSlug(slug))}`),
+        confirmTossPayment: (input) => req(`/api/frontend/payments/toss/confirm`, { method: "POST", body: JSON.stringify(input) }, true),
+        listOrders: () => req(`/api/frontend/orders`, {}, true),
+        getOrder: (id, opts) => req(`/api/frontend/orders/${id}${opts?.guestToken ? `?guestToken=${q(opts.guestToken)}` : ""}`, {}, true),
+        lookupOrder: (input) => req(`/api/frontend/orders/lookup`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        }),
+        claimOrder: (id, guestToken) => req(`/api/frontend/orders/${id}/claim`, { method: "POST", body: JSON.stringify({ guestToken }) }, true),
+        createOrder: (input) => req(`/api/frontend/orders`, { method: "POST", body: JSON.stringify(input) }, true),
+        register: (input) => req(`/api/frontend/auth/register`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        }),
+        login: (input) => req(`/api/frontend/auth/login`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        }),
+        me: () => req(`/api/frontend/auth/me`, {}, true),
+        getProviders: (slug) => req(`/api/frontend/auth/providers?business=${q(requireSlug(slug))}`),
+        updateProfile: (input) => req(`/api/frontend/profile`, { method: "PUT", body: JSON.stringify(input) }, true),
+        oauthStartUrl: (provider, returnUrl, slug) => `${apiBase}/api/frontend/auth/${provider}/start?slug=${q(requireSlug(slug))}&return=${q(returnUrl)}`,
+        listReviews: (params) => {
+            const sp = new URLSearchParams();
+            sp.set("productId", String(params.productId));
+            sp.set("businessSlug", params.businessSlug);
+            if (params.rating != null)
+                sp.set("rating", String(params.rating));
+            if (params.status)
+                sp.set("status", params.status);
+            if (params.page != null)
+                sp.set("page", String(params.page));
+            if (params.limit != null)
+                sp.set("limit", String(params.limit));
+            return req(`/api/frontend/reviews?${sp.toString()}`);
+        },
+        getMetaConfig: (slug) => req(`/api/frontend/meta/config?business=${q(requireSlug(slug))}`),
+    };
+}

package/dist/draft.d.ts

@@ -0,0 +1,17 @@
+import type { CartItemInput } from "./types";
+export interface CheckoutDraft {
+    items: CartItemInput[];
+    customer_name: string;
+    phone: string;
+    address: string;
+    email?: string | null;
+    amount: number;
+    businessSlug?: string;
+    /** 바로구매(단품) 주문 — true 면 결제 성공 후 장바구니를 비우지 않는다(카트 보존) */
+    instant?: boolean;
+}
+export declare function saveDraft(orderId: string, draft: CheckoutDraft): void;
+export declare function readDraft(orderId: string): CheckoutDraft | null;
+export declare function clearDraft(orderId: string): void;
+export declare function saveGuestToken(orderId: number, guestToken: string): void;
+export declare function readGuestToken(orderId: number): string | null;

package/dist/draft.js

@@ -0,0 +1,45 @@
+const PREFIX = "sello_toss_draft_";
+export function saveDraft(orderId, draft) {
+    try {
+        localStorage.setItem(PREFIX + orderId, JSON.stringify(draft));
+    }
+    catch {
+        // localStorage 불가해도 결제는 진행 (성공 페이지에서 안내)
+    }
+}
+export function readDraft(orderId) {
+    try {
+        const raw = localStorage.getItem(PREFIX + orderId);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function clearDraft(orderId) {
+    try {
+        localStorage.removeItem(PREFIX + orderId);
+    }
+    catch {
+        // ignore
+    }
+}
+// 비회원 주문 열람 토큰 — 결제 승인 응답의 guest_token 을 주문번호별로 보관.
+// (회원 주문은 로그인 토큰으로 열람하므로 저장하지 않는다)
+const GUEST_PREFIX = "sello_guest_order_";
+export function saveGuestToken(orderId, guestToken) {
+    try {
+        localStorage.setItem(GUEST_PREFIX + orderId, guestToken);
+    }
+    catch {
+        // ignore
+    }
+}
+export function readGuestToken(orderId) {
+    try {
+        return localStorage.getItem(GUEST_PREFIX + orderId);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./business";
+export * from "./cart";
+export * from "./draft";
+export * from "./client";

package/dist/index.js

@@ -0,0 +1,7 @@
+// @repo/commerce — 프레임워크 무관 코어 (타입 + 클라이언트 + 장바구니/주소 로직).
+// React 훅/컴포넌트는 "@repo/commerce/react" 에서 import.
+export * from "./types";
+export * from "./business";
+export * from "./cart";
+export * from "./draft";
+export * from "./client";

package/dist/react/TossPaymentWidget.d.ts

@@ -0,0 +1,42 @@
+type TossWidgets = {
+    setAmount: (a: {
+        currency: string;
+        value: number;
+    }) => Promise<void>;
+    renderPaymentMethods: (o: {
+        selector: string;
+        variantKey: string;
+    }) => Promise<void>;
+    requestPayment: (o: Record<string, unknown>) => Promise<void>;
+};
+type TossPaymentsFn = (clientKey: string) => {
+    widgets: (o: {
+        customerKey: string;
+    }) => TossWidgets;
+};
+declare global {
+    interface Window {
+        TossPayments?: TossPaymentsFn;
+    }
+}
+export interface PayRequest {
+    orderId: string;
+    orderName: string;
+    successUrl: string;
+    failUrl: string;
+    customerName?: string;
+    customerEmail?: string;
+    customerMobilePhone?: string;
+}
+export interface TossPaymentWidgetProps {
+    clientKey: string;
+    amount: number;
+    customerKey: string;
+    /** 결제수단 위젯을 그릴 컨테이너 id (기본 toss-payment-method) */
+    selector?: string;
+    onReady?: (pay: (req: PayRequest) => Promise<void>) => void;
+    onError?: (msg: string) => void;
+    className?: string;
+}
+export declare function TossPaymentWidget({ clientKey, amount, customerKey, selector, onReady, onError, className, }: TossPaymentWidgetProps): import("react").JSX.Element;
+export {};

package/dist/react/TossPaymentWidget.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+const SDK_SRC = "https://js.tosspayments.com/v2/standard";
+export function TossPaymentWidget({ clientKey, amount, customerKey, selector = "toss-payment-method", onReady, onError, className, }) {
+    const widgetsRef = useRef(null);
+    const [status, setStatus] = useState(clientKey ? "loading" : "error");
+    // 콜백/금액을 ref 로 보관 → init effect 는 clientKey/customerKey 에만 의존.
+    const amountRef = useRef(amount);
+    const onReadyRef = useRef(onReady);
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+        amountRef.current = amount;
+        onReadyRef.current = onReady;
+        onErrorRef.current = onError;
+    });
+    useEffect(() => {
+        if (!clientKey)
+            return;
+        let cancelled = false;
+        function start() {
+            if (cancelled || !window.TossPayments)
+                return;
+            const widgets = window.TossPayments(clientKey).widgets({ customerKey });
+            widgetsRef.current = widgets;
+            void (async () => {
+                await widgets.setAmount({ currency: "KRW", value: amountRef.current });
+                await widgets.renderPaymentMethods({
+                    selector: `#${selector}`,
+                    variantKey: "DEFAULT",
+                });
+                if (cancelled)
+                    return;
+                setStatus("ready");
+                const pay = async (req) => {
+                    await widgets.setAmount({ currency: "KRW", value: amountRef.current });
+                    await widgets.requestPayment({
+                        orderId: req.orderId,
+                        orderName: req.orderName,
+                        successUrl: req.successUrl,
+                        failUrl: req.failUrl,
+                        customerName: req.customerName,
+                        customerEmail: req.customerEmail,
+                        customerMobilePhone: req.customerMobilePhone,
+                    });
+                };
+                onReadyRef.current?.(pay);
+            })().catch(() => {
+                if (cancelled)
+                    return;
+                setStatus("error");
+                onErrorRef.current?.("결제 위젯을 불러오지 못했습니다.");
+            });
+        }
+        if (window.TossPayments) {
+            start();
+        }
+        else {
+            const existing = document.querySelector(`script[src="${SDK_SRC}"]`);
+            if (existing) {
+                existing.addEventListener("load", start);
+            }
+            else {
+                const s = document.createElement("script");
+                s.src = SDK_SRC;
+                s.async = true;
+                s.onload = start;
+                document.head.appendChild(s);
+            }
+        }
+        return () => {
+            cancelled = true;
+        };
+    }, [clientKey, customerKey, selector]);
+    // 금액 변경 시 위젯에 반영
+    useEffect(() => {
+        if (status === "ready" && widgetsRef.current) {
+            void widgetsRef.current.setAmount({ currency: "KRW", value: amount });
+        }
+    }, [amount, status]);
+    return (_jsxs("div", { className: className, children: [status === "loading" && _jsx("p", { children: "\uACB0\uC81C \uC218\uB2E8 \uBD88\uB7EC\uC624\uB294 \uC911\u2026" }), status === "error" && (_jsx("p", { children: "\uACB0\uC81C \uC124\uC815\uC744 \uBD88\uB7EC\uC624\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. (\uAD00\uB9AC\uC790\uC5D0\uC11C Toss \uD0A4 \uD655\uC778)" })), _jsx("div", { id: selector })] }));
+}

package/dist/react/index.d.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react";
+import type { SelloClient } from "../client";
+import type { AuthUser, CartItem, Order, PaymentConfig } from "../types";
+export interface CartApi {
+    items: CartItem[];
+    count: number;
+    total: number;
+    add: (item: CartItem) => void;
+    setQty: (key: string, qty: number) => void;
+    remove: (key: string) => void;
+    clear: () => void;
+}
+export interface SelloContextValue {
+    client: SelloClient;
+    businessSlug: string | null;
+    apiBase: string;
+    token: string | null;
+    user: AuthUser | null;
+    authReady: boolean;
+    oauthError: string | null;
+    login: (email: string, password: string) => Promise<void>;
+    register: (email: string, password: string, name?: string) => Promise<void>;
+    logout: () => void;
+    cart: CartApi;
+}
+export interface SelloProviderProps {
+    children: ReactNode;
+    /** API 베이스. "" = 동일 출처. 예: "https://www.sello.sh" */
+    apiBase?: string;
+    /** 가게 slug 를 명시 (SSR/Next 권장). 없으면 서브도메인/쿼리로 자동 해석 */
+    businessSlug?: string | null;
+    /** 자동 해석 실패 시 폴백 slug */
+    fallbackSlug?: string | null;
+    tokenStorageKey?: string;
+}
+export declare function SelloProvider({ children, apiBase, businessSlug, fallbackSlug, tokenStorageKey, }: SelloProviderProps): import("react").JSX.Element;
+export declare function useSello(): SelloContextValue;
+export declare function useAuth(): {
+    user: AuthUser | null;
+    token: string | null;
+    authReady: boolean;
+    oauthError: string | null;
+    login: (email: string, password: string) => Promise<void>;
+    register: (email: string, password: string, name?: string) => Promise<void>;
+    logout: () => void;
+    isLoggedIn: boolean;
+};
+export declare function useCart(): CartApi;
+export declare function useProducts(slug?: string): {
+    products: import("..").Product[];
+    business: {
+        id: number;
+        name: string;
+        slug: string;
+    } | null;
+    loading: boolean;
+    error: string | null;
+};
+export declare function useProduct(id: number | null, slug?: string): {
+    product: import("..").Product | null;
+    variants: import("..").Variant[];
+    loading: boolean;
+    error: string | null;
+};
+export declare function usePaymentConfig(slug?: string): {
+    config: PaymentConfig | null;
+    error: string | null;
+};
+export declare function useOrders(): {
+    orders: Order[];
+    loading: boolean;
+    error: string | null;
+};
+export declare function useOrder(id: number | null, opts?: {
+    guestToken?: string;
+}): {
+    order: Order | null;
+    items: import("..").OrderItem[];
+    loading: boolean;
+    error: string | null;
+};
+export { TossPaymentWidget } from "./TossPaymentWidget";
+export type { PayRequest, TossPaymentWidgetProps } from "./TossPaymentWidget";

package/dist/react/index.js

@@ -0,0 +1,369 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// @repo/commerce/react — SelloProvider + 훅.
+// 가게 식별(slug), 인증 토큰, 장바구니 상태/영속을 한곳에서 관리.
+// Vite·Next(App Router)·AI생성 스토어 어디서나 동작 (SSR 안전).
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { createSelloClient } from "../client";
+import { resolveBusinessSlug } from "../business";
+import { addToCart, cartCount, cartTotal, removeFromCart, setCartQty, } from "../cart";
+const Ctx = createContext(null);
+export function SelloProvider({ children, apiBase = "", businessSlug, fallbackSlug, tokenStorageKey = "sello_token", }) {
+    // ── slug: prop 우선, 없으면 클라에서 해석 ──
+    const [slug, setSlug] = useState(businessSlug ?? null);
+    useEffect(() => {
+        if (businessSlug != null) {
+            setSlug(businessSlug);
+            return;
+        }
+        setSlug(resolveBusinessSlug({ fallback: fallbackSlug }));
+    }, [businessSlug, fallbackSlug]);
+    // ── token ──
+    const [token, setToken] = useState(null);
+    const tokenRef = useRef(null);
+    useEffect(() => {
+        tokenRef.current = token;
+    }, [token]);
+    const persistToken = useCallback((t) => {
+        setToken(t);
+        tokenRef.current = t;
+        try {
+            if (t)
+                localStorage.setItem(tokenStorageKey, t);
+            else
+                localStorage.removeItem(tokenStorageKey);
+        }
+        catch {
+            /* ignore */
+        }
+    }, [tokenStorageKey]);
+    // client (apiBase/slug 변할 때만 재생성; 토큰은 ref 로 최신값 주입)
+    const client = useMemo(() => createSelloClient({
+        apiBase,
+        businessSlug: slug,
+        getToken: () => tokenRef.current,
+    }), [apiBase, slug]);
+    // ── 초기 토큰 로드 + OAuth #token= 캡처 ──
+    const [user, setUser] = useState(null);
+    const [authReady, setAuthReady] = useState(false);
+    const [oauthError, setOauthError] = useState(null);
+    useEffect(() => {
+        let initial = null;
+        try {
+            initial = localStorage.getItem(tokenStorageKey);
+        }
+        catch {
+            /* ignore */
+        }
+        if (typeof window !== "undefined" &&
+            (window.location.hash.includes("token=") ||
+                window.location.hash.includes("error="))) {
+            const h = new URLSearchParams(window.location.hash.slice(1));
+            const t = h.get("token");
+            const err = h.get("error");
+            if (t) {
+                initial = t;
+                try {
+                    localStorage.setItem(tokenStorageKey, t);
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+            if (err)
+                setOauthError(err);
+            history.replaceState(null, "", window.location.pathname + window.location.search);
+        }
+        if (initial) {
+            setToken(initial);
+            tokenRef.current = initial;
+        }
+        else {
+            setAuthReady(true);
+        }
+    }, [tokenStorageKey]);
+    // 토큰 있으면 유저 조회
+    useEffect(() => {
+        let cancelled = false;
+        if (!token) {
+            setUser(null);
+            return;
+        }
+        client
+            .me()
+            .then((r) => {
+            if (!cancelled)
+                setUser(r.user);
+        })
+            .catch(() => {
+            if (!cancelled) {
+                persistToken(null);
+                setUser(null);
+            }
+        })
+            .finally(() => {
+            if (!cancelled)
+                setAuthReady(true);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [token, client, persistToken]);
+    // ── 장바구니 (slug 별 localStorage 영속, SSR 안전) ──
+    const [items, setItems] = useState([]);
+    const hydratedRef = useRef(false);
+    const cartKey = slug ? `sello_cart_${slug}` : null;
+    useEffect(() => {
+        if (!cartKey)
+            return;
+        try {
+            const raw = localStorage.getItem(cartKey);
+            setItems(raw ? JSON.parse(raw) : []);
+        }
+        catch {
+            setItems([]);
+        }
+        hydratedRef.current = true;
+    }, [cartKey]);
+    useEffect(() => {
+        if (!cartKey || !hydratedRef.current)
+            return;
+        try {
+            localStorage.setItem(cartKey, JSON.stringify(items));
+        }
+        catch {
+            /* ignore */
+        }
+    }, [items, cartKey]);
+    const cart = useMemo(() => ({
+        items,
+        count: cartCount(items),
+        total: cartTotal(items),
+        add: (item) => setItems((prev) => addToCart(prev, item)),
+        setQty: (key, qty) => setItems((prev) => setCartQty(prev, key, qty)),
+        remove: (key) => setItems((prev) => removeFromCart(prev, key)),
+        clear: () => setItems([]),
+    }), [items]);
+    const login = useCallback(async (email, password) => {
+        if (!slug)
+            throw new Error("가게가 식별되지 않았습니다.");
+        const r = await client.login({ slug, email, password });
+        persistToken(r.token);
+        setUser(r.user);
+    }, [client, slug, persistToken]);
+    const register = useCallback(async (email, password, name) => {
+        if (!slug)
+            throw new Error("가게가 식별되지 않았습니다.");
+        const r = await client.register({ slug, email, password, name });
+        persistToken(r.token);
+        setUser(r.user);
+    }, [client, slug, persistToken]);
+    const logout = useCallback(() => {
+        persistToken(null);
+        setUser(null);
+    }, [persistToken]);
+    const value = {
+        client,
+        businessSlug: slug,
+        apiBase,
+        token,
+        user,
+        authReady,
+        oauthError,
+        login,
+        register,
+        logout,
+        cart,
+    };
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+export function useSello() {
+    const ctx = useContext(Ctx);
+    if (!ctx)
+        throw new Error("useSello 는 <SelloProvider> 안에서만 사용하세요.");
+    return ctx;
+}
+export function useAuth() {
+    const { user, token, authReady, oauthError, login, register, logout } = useSello();
+    return {
+        user,
+        token,
+        authReady,
+        oauthError,
+        login,
+        register,
+        logout,
+        isLoggedIn: !!user,
+    };
+}
+export function useCart() {
+    return useSello().cart;
+}
+export function useProducts(slug) {
+    const { client } = useSello();
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const effSlug = slug ?? client.businessSlug;
+    useEffect(() => {
+        let cancelled = false;
+        if (!effSlug)
+            return;
+        setLoading(true);
+        setError(null);
+        client
+            .listProducts(effSlug)
+            .then((r) => {
+            if (!cancelled)
+                setData(r);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "오류");
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, effSlug]);
+    return {
+        products: data?.products ?? [],
+        business: data?.business ?? null,
+        loading,
+        error,
+    };
+}
+export function useProduct(id, slug) {
+    const { client } = useSello();
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const effSlug = slug ?? client.businessSlug;
+    useEffect(() => {
+        let cancelled = false;
+        if (id == null || !effSlug)
+            return;
+        setLoading(true);
+        setError(null);
+        client
+            .getProduct(id, effSlug)
+            .then((r) => {
+            if (!cancelled)
+                setData(r);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "오류");
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, id, effSlug]);
+    return {
+        product: data?.product ?? null,
+        variants: data?.variants ?? [],
+        loading,
+        error,
+    };
+}
+export function usePaymentConfig(slug) {
+    const { client } = useSello();
+    const [config, setConfig] = useState(null);
+    const [error, setError] = useState(null);
+    const effSlug = slug ?? client.businessSlug;
+    useEffect(() => {
+        let cancelled = false;
+        if (!effSlug)
+            return;
+        client
+            .getPaymentConfig(effSlug)
+            .then((c) => {
+            if (!cancelled)
+                setConfig(c);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "오류");
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, effSlug]);
+    return { config, error };
+}
+export function useOrders() {
+    const { client, token } = useSello();
+    const [orders, setOrders] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        if (!token) {
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        client
+            .listOrders()
+            .then((r) => {
+            if (!cancelled)
+                setOrders(r.orders);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "오류");
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, token]);
+    return { orders, loading, error };
+}
+export function useOrder(id, opts) {
+    const { client } = useSello();
+    const [data, setData] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const guestToken = opts?.guestToken;
+    useEffect(() => {
+        let cancelled = false;
+        if (id == null)
+            return;
+        setLoading(true);
+        client
+            .getOrder(id, guestToken ? { guestToken } : undefined)
+            .then((r) => {
+            if (!cancelled)
+                setData(r);
+        })
+            .catch((e) => {
+            if (!cancelled)
+                setError(e instanceof Error ? e.message : "오류");
+        })
+            .finally(() => {
+            if (!cancelled)
+                setLoading(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [client, id, guestToken]);
+    return {
+        order: data?.order ?? null,
+        items: data?.items ?? [],
+        loading,
+        error,
+    };
+}
+export { TossPaymentWidget } from "./TossPaymentWidget";

package/dist/types.d.ts

@@ -0,0 +1,173 @@
+export interface ProductOption {
+    name: string;
+    values: string[];
+}
+export interface Product {
+    id: number;
+    name: string;
+    description: string | null;
+    price: number;
+    currency: string;
+    image_url: string | null;
+    options?: ProductOption[];
+    stock?: number | null;
+    /** true 면 스토어가 상품 상세를 자체 코드로 렌더 (chaae 의 custom_detail) */
+    custom_detail?: boolean;
+}
+export interface Variant {
+    options: Record<string, string>;
+    stock: number;
+    price: number | null;
+}
+export interface ProductListResult {
+    business: {
+        id: number;
+        name: string;
+        slug: string;
+    };
+    products: Product[];
+}
+export interface ProductDetailResult {
+    product: Product;
+    variants: Variant[];
+}
+export interface CartItem {
+    productId: number;
+    name: string;
+    image_url: string | null;
+    options: Record<string, string>;
+    unitPrice: number;
+    currency: string;
+    quantity: number;
+    maxStock: number | null;
+}
+/** 서버로 보내는 주문 아이템 — 가격·재고는 서버가 재검증한다(클라 신뢰 X). */
+export interface CartItemInput {
+    product_id: number;
+    options?: Record<string, string>;
+    quantity: number;
+}
+export type OrderStatus = "pending" | "paid" | "preparing" | "shipped" | "delivered" | "cancelled" | "refunded";
+export interface OrderItem {
+    id?: number;
+    order_id?: number;
+    product_id?: number;
+    name: string;
+    variant_options: Record<string, string>;
+    unit_price: number;
+    quantity: number;
+}
+export interface Order {
+    id: number;
+    status: OrderStatus | string;
+    total: number;
+    customer_name?: string;
+    phone?: string;
+    address?: string;
+    email?: string | null;
+    created_at?: string;
+    carrier?: string | null;
+    carrier_name?: string | null;
+    tracking_number?: string | null;
+    tracking_url?: string | null;
+}
+export interface OrderWithItems {
+    order: Order;
+    items: OrderItem[];
+}
+export interface AuthUser {
+    id: number;
+    email: string;
+    name: string;
+    user_type: string;
+    business_id: number | null;
+    phone?: string | null;
+    postal_code?: string | null;
+    address?: string | null;
+    address_detail?: string | null;
+}
+export interface AuthResult {
+    token: string;
+    user: AuthUser;
+}
+export interface AuthProviders {
+    google: boolean;
+    kakao: boolean;
+}
+export interface ProfileInput {
+    name?: string;
+    phone?: string;
+    postal_code?: string;
+    address?: string;
+    address_detail?: string;
+}
+export interface PaymentConfig {
+    provider: string;
+    tossClientKey: string;
+}
+/** 토스 결제 승인 입력 — 서버가 buildOrder 로 가격·재고 재검증 후 total === amount 확인. */
+export interface ConfirmTossInput {
+    paymentKey: string;
+    orderId: string;
+    amount: number;
+    items: CartItemInput[];
+    customer_name: string;
+    phone: string;
+    address: string;
+    email?: string;
+    businessSlug?: string;
+}
+export interface ConfirmTossResult {
+    order: {
+        id: number;
+        total: number;
+        status: string;
+    };
+    guest_token: string | null;
+}
+export interface Review {
+    id: number;
+    order_id: number;
+    product_id: number;
+    user_id: number;
+    rating: number;
+    title: string | null;
+    content: string | null;
+    images: string[] | null;
+    status: "pending" | "approved" | "rejected" | "hidden";
+    is_verified_purchase: boolean;
+    admin_reply: string | null;
+    admin_reply_date: string | null;
+    created_at: string;
+    updated_at: string;
+    user_name: string | null;
+    user_email: string | null;
+    product_name: string | null;
+}
+export interface ReviewListResult {
+    reviews: Review[];
+    page: number;
+    limit: number;
+    total: number;
+    hasMore: boolean;
+}
+export interface ReviewListParams {
+    productId: number;
+    businessSlug: string;
+    rating?: number;
+    status?: Review["status"];
+    page?: number;
+    limit?: number;
+}
+export interface MetaConfig {
+    enabled: boolean;
+    pixelId: string | null;
+}
+export interface CheckoutValues {
+    customer_name: string;
+    phone: string;
+    address: string;
+    email?: string;
+    postal_code?: string;
+    address_detail?: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Sello 커머스 공유 타입 — 모든 스토어프론트가 이 타입 위에서 동작한다.
+// (두 스토어가 각자 types.ts 를 중복 정의하던 것을 여기로 통합)
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sellosh/commerce",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "description": "Sello 커머스 SDK — 모든 스토어프론트(손코딩/AI생성)가 공유하는 타입드 클라이언트 + React 훅. 결제·재고·인증의 안전 경계를 한 곳에 둔다.",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}