Storefront SDK

npm install @sayren/storefront-sdk

import { createStorefrontClient } from "@sayren/storefront-sdk";

const sdk = createStorefrontClient({
  baseUrl: "https://api.sayren.io/storefront/v1",
  storeCode: "{상점 코드}", // X-Store-Code. api.sayren.io이면 필수
  cartToken: () => localStorage.getItem("cartToken"), // 비회원 장바구니 X-Cart-Token
  onCartToken: (token) => localStorage.setItem("cartToken", token), // 서버가 새 토큰을 줬을 때
});

import { createStorefrontClient, createStorefrontSession } from "@sayren/storefront-sdk";

const session = createStorefrontSession({
  baseUrl: "https://api.sayren.io/storefront/v1",
  storeCode: "{상점 코드}",
  storage: {
    get: (key) => localStorage.getItem(key),
    set: (key, value) => localStorage.setItem(key, value),
    remove: (key) => localStorage.removeItem(key),
  },
});

await session.login({ email: "buyer@example.com", password: "{비밀번호}" });

const sdk = createStorefrontClient({ baseUrl: "https://api.sayren.io/storefront/v1", storeCode: "{상점 코드}", session });

const tokens = await sdk.auth.login({ email: "buyer@example.com", password: "{비밀번호}" });
// { accessToken, refreshToken, expiresIn } — expiresIn은 초

const rotated = await sdk.auth.refresh(tokens.refreshToken); // rotation — 새 쌍을 받고 이전 토큰은 폐기
await sdk.auth.logout();
// signup({ email, password, name, phone?, agreements: { terms: true, privacy: true, marketing }, cartToken? })도 같은 토큰 쌍을 준다

const categories = await sdk.catalog.listCategories();

// sort: recommend · latest · priceAsc · priceDesc …
const page = await sdk.catalog.searchProducts({ keyword: "티셔츠", page: 1, size: 20, sort: "priceAsc" });

const product = await sdk.catalog.getProduct("prod_001");
// product.optionGroups: [{ groupId, name, values: [{ valueId, name }] }]
// product.variants:     [{ variantId, valueIds, name: "화이트 / M", additionalPrice, soldOut }]

await sdk.catalog.listProductReviews("prod_001", { sort: "helpful" });
// 옵션별 리뷰 — 상세의 variants[].variantId. 리뷰 항목의 variantId와 같은 값입니다
await sdk.catalog.listProductReviews("prod_001", { variantId: product.variants[0].variantId, hasImage: true });
await sdk.catalog.listProductInquiries("prod_001", { page: 1 });
// category: PRODUCT(기본) · DELIVERY · RETURN · EXCHANGE · ETC
await sdk.catalog.createInquiry("prod_001", { content: "언제 발송되나요?", secret: true, category: "DELIVERY" });

const { contents: collections } = await sdk.catalog.listCollections();
const collection = await sdk.catalog.getCollection("chuseok"); // 숨김·기간 밖은 404 COLLECTION_NOT_FOUND
// sort: manual(셀러가 정한 순서) · recommend · latest · priceAsc … 생략하면 collection.productSort
const items = await sdk.catalog.listCollectionProducts("chuseok", { page: 1, size: 20 });

const price = product.discountedPrice ?? product.salePrice;
const compareAt =
  product.originalPrice !== null && product.originalPrice > price
    ? product.originalPrice
    : product.discountedPrice !== null
      ? product.salePrice
      : null;
const rate = compareAt ? Math.round((1 - price / compareAt) * 100) : null;

const store = await sdk.store.get();
// { storeCode, name, logoUrl, customerCenterPhone, businessHours, guestCheckout, loginMethods,
//   checkoutAvailable, checkoutMode, checkoutUnavailableReason,
//   businessName, representativeName, businessNumber, mailOrderSalesNumber, businessAddress,
//   customerCenterEmail, privacyOfficerName, privacyOfficerEmail }

if (!store.checkoutAvailable) {
  return <p>지금은 온라인 주문을 받지 않습니다</p>;
}

const cart = await sdk.cart.addItem({
  productId: "prod_001",
  optionId: product.variants[0].variantId, // 옵션 없는 상품은 생략
  quantity: 2,
});

await sdk.cart.get();
await sdk.cart.updateItem(cart.items[0].cartItemId, { quantity: 3 });
await sdk.cart.removeItem(cart.items[0].cartItemId);

import { createPayments } from "@sayren/storefront-sdk/payments";

const payments = createPayments({ client: sdk, returnUrl: `${location.origin}/checkout/return` });

// 1. 주문서 — 결제 옵션(PG·결제수단·간편결제사) 목록이 같이 온다
const checkout = await sdk.checkout.create({ cartItemIds: [cart.items[0].cartItemId] });

// 2. 결제 시작 — 팝업이면 결과가 오고, 리다이렉트면 페이지를 떠난다
const result = await payments.start(checkout.checkoutId, {
  option: checkout.paymentOptions[0],
  shippingAddress,
}); // result.status: COMPLETED · CANCELED · FAILED · PROCESSING · INVALID

// 3. 복귀 화면 — 리다이렉트로 돌아온 구매자
const returned = await payments.result();

const orders = await sdk.myOrders.list({ status: "DELIVERED" });
// 주문마다 testPayment. payment.method는 실제 결제수단(간편결제는 EASY_PAY)
const order = await sdk.myOrders.get("order_001");

// 비회원 주문 조회 (주문 조회 비밀번호는 주문할 때 적은 6자 이상 값)
await sdk.myOrders.getGuestOrder("order_001", { phone: "01012345678", orderPassword: "guest1234" });

// 배송 조회 / 구매 확정
const delivery = await sdk.myOrders.getDelivery("oi_001");
// trackingStage: ACCEPTED·IN_TRANSIT·OUT_FOR_DELIVERY·DELIVERED(조회 전 null)
// trackingEvents: 추적 이력(오래된 순, status는 택배사 원문), trackingCheckedAt: 마지막 조회 시각
await sdk.myOrders.decidePurchase("oi_001");

// 클레임 (CANCEL · RETURN · EXCHANGE)
await sdk.myClaims.create("oi_001", { type: "RETURN", reason: "CHANGE_OF_MIND", reasonDetail: "사이즈가 맞지 않아요" });
await sdk.myClaims.list({ status: "REQUESTED" });
await sdk.myClaims.withdraw("claim_001");

try {
  await sdk.myOrders.getGuestOrder(orderId, { phone, orderPassword });
} catch (error) {
  if (error instanceof ApiError && error.status === 429) {
    const minutes = Math.ceil(Number(error.details?.retryAfterSeconds ?? 60) / 60);
    showMessage(`조회 시도가 너무 많습니다. ${minutes}분 뒤에 다시 시도해 주십시오`);
  }
}

await sdk.member.me();
await sdk.member.updateMe({ name: "홍길동" });
// 배송지 listAddresses·createAddress·updateAddress·deleteAddress, 찜 listWishlist·addWishlist·removeWishlist

await sdk.reviews.listWritable();
await sdk.reviews.create("oi_001", { rating: 5, content: "배송도 빠르고 품질도 좋았습니다" }); // 10자 이상

// 리뷰 사진 — 자리를 받아 파일을 PUT하고 url을 images에 넣습니다(최대 5장)
const ticket = await sdk.reviews.createImageUpload({ filename: file.name, size: file.size });
await fetch(ticket.uploadUrl, { method: "PUT", body: file });
await sdk.reviews.create("oi_002", { rating: 5, content: "사진처럼 색감이 예쁩니다", images: [ticket.url] });

// 내가 쓴 리뷰 — 최신순. 항목의 reviewId로 수정·삭제합니다
const mine = await sdk.reviews.listMine({ page: 1, size: 20 });
// 항목마다 productId·productName·thumbnailUrl·optionName·rating·content·images·sellerReply·blinded·editable·editableUntil·createdAt
if (mine.contents[0]?.editable) {
  await sdk.reviews.update(mine.contents[0].reviewId, { rating: 4 });
}

await sdk.inquiries.listMine({ answered: false });
// 항목마다 productId·productName·thumbnailUrl·category — 상품 상세로 돌아가는 링크를 만들 수 있습니다

import { ApiError } from "@sayren/storefront-sdk";

try {
  await sdk.cart.addItem({ productId: "prod_x", quantity: 1 });
} catch (error) {
  if (error instanceof ApiError && error.code === "INSUFFICIENT_STOCK") showToast("재고가 부족합니다");
}