구매자 인증

구매자 계정은 sayren이 보관해요. 스토어프론트는 로그인·가입 화면을 자유롭게 디자인하고, @sayren/storefront-sdk/auth의 메서드로 결과만 받아요. 스토어프론트에 따로 데이터베이스를 둘 필요가 없어요.

어느 방식으로 로그인해도 결과는 같은 구매자 토큰이에요. 이 토큰으로 /me/*, 장바구니, 주문 API를 그대로 호출해요.

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

const auth = createStorefrontAuth({
  baseUrl: "https://api.sayren.app/storefront/v1",
  storeCode: "mystore",
});

토큰 쌍은 { accessToken, refreshToken, expiresIn }이에요. 액세스 토큰은 30분, 리프레시 토큰은 14일 동안 쓸 수 있어요.

토큰은 서버에 보관하기

로그인은 스토어프론트 서버(라우트 action, 서버 함수)에서 호출하고, 받은 토큰은 HttpOnly 쿠키에 넣기를 권해요. 브라우저 스크립트가 토큰을 읽을 수 없으니 스크립트 삽입 공격으로 토큰이 새지 않아요.

// 로그인 action 예시
const tokens = await auth.session({ email, password, cartToken });
const expiresAt = Date.now() + tokens.expiresIn * 1000;
// { accessToken, refreshToken, expiresAt }를 HttpOnly 쿠키에 저장

요청마다 쿠키의 expiresAt을 보고, 만료가 가까우면 refresh()로 새 쌍을 받아 쿠키를 바꿔요. 리프레시 토큰은 한 번 쓰면 폐기되니 새로 받은 쌍으로 꼭 바꿔 저장해요. refresh()가 401 INVALID_REFRESH_TOKEN으로 실패하면 쿠키를 지우고 로그아웃 상태로 보여 주세요.

비회원

로그인하지 않은 구매자는 비회원 세션을 써요. 구매자 계정을 만들지 않고, 장바구니와 비회원 주문만 이 세션에 쌓여요. /me/*처럼 계정이 필요한 API에는 쓸 수 없어요.

const guest = await auth.anonymous();
// guest.cartToken을 쿠키에 보관하고 스토어프론트 클라이언트의 cartToken 옵션으로 보낸다

anonymous()를 따로 부르지 않아도 돼요. 장바구니 API는 토큰 없이 호출하면 같은 세션을 발급해 응답 헤더 X-Cart-Token으로 돌려줘요. 스토어프론트 클라이언트의 onCartToken 콜백으로 받아 저장하면 돼요.

• 마지막 활동 후 30일이 지나면 세션이 만료되고 담긴 장바구니도 지워져요. 쓸 때마다 기한이 늘어나요.
• 만료됐거나 모르는 토큰으로 장바구니를 부르면 새 세션이 발급돼요. onCartToken으로 온 값은 항상 저장하세요.
• 담은 적 없는 세션은 하루 뒤 지워져요.

로그인하면 장바구니 합치기

session()이나 signUp()에 비회원 cartToken을 함께 보내면 비회원 장바구니가 회원 장바구니로 합쳐져요. 같은 상품·옵션은 수량을 더해요. 합친 뒤에는 그 비회원 세션이 닫히니 스토어프론트도 비회원 토큰 쿠키를 지워요.

const tokens = await auth.session({ email, password, cartToken: guestCartToken });
// 비회원 토큰 쿠키 삭제, 이후 장바구니는 accessToken으로 조회

탈퇴

로그인한 구매자가 비밀번호로 본인 확인을 하고 계정을 지워요. 되돌릴 수 없으니 화면에서 한 번 더 확인받으세요.

await auth.withdraw(accessToken, { password });
// 성공하면 보관한 토큰 쿠키를 지운다

• 계정, 배송지, 위시리스트, 장바구니, 적립금이 지워지고 발급된 토큰은 모두 무효가 돼요.
• 주문, 취소·반품·교환, 리뷰, 문의 기록은 스토어가 보관해요. 같은 이메일로 다시 가입해도 옛 주문은 보이지 않아요.
• 결제 대기부터 배송 중인 주문, 처리 중인 클레임, 진행 중인 결제가 있으면 409 WITHDRAWAL_BLOCKED예요. error.details의 inProgressOrderItems·openClaims·pendingPayments로 무엇이 남았는지 안내해요.
• 비밀번호가 틀리면 403 PASSWORD_MISMATCH예요. 로그인과 같이 5번 연속 틀리면 10분 동안 잠겨요.

에러

실패는 ApiError로 올라와요. error.code로 나눠 화면에 안내해요.