@sayren/storefront-sdk 0.9.0 → 0.11.0

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { a as AnonymousSession, d as SignupRequest, f as SocialProvider, h as WithdrawalBlockedDetails, l as LoginRequest, m as WithdrawRequest, p as TokenPair, t as ApiError, u as MemberIdentities } from "../http-BbFHVGBf.mjs";
+import { a as AnonymousSession, d as MemberIdentities, f as SignupRequest, g as WithdrawalBlockedDetails, h as WithdrawRequest, m as TokenPair, p as SocialProvider, t as ApiError, u as LoginRequest } from "../http-CeRVoUGu.mjs";
 //#region src/auth/index.d.ts
 /** 소셜 로그인 시작 결과 — `codeVerifier`와 `state`는 돌아올 때까지 서버 세션(httpOnly 쿠키 등)에 보관한다 */
 export interface IdpStart {
@@ -56,14 +56,23 @@ export declare function createStorefrontAuth(options: StorefrontAuthOptions): {
   /**
    * 소셜 로그인 시작 — PKCE(S256)와 state를 만들고 공급자 로그인 주소를 받는다. 반환한 `state`·`codeVerifier`를
    * 서버 세션에 보관하고 구매자를 `url`로 보낸다. 로그인을 마치면 `redirectUri`로 `?code=&state=`가 붙어 돌아온다.
-   * `redirectUri`는 스토어프론트 도메인 목록 안이어야 한다
+   * `redirectUri`는 스토어프론트 도메인 목록 안이어야 한다.
+   *
+   * 가입 화면에서 받은 약관 동의는 `agreements`로 함께 보낸다. **이 로그인으로 가입이 되는 경우에만** 이력에
+   * 남고(기존 회원의 로그인이면 무시한다), 보내지 않으면 가입은 되지만 필수 동의 이력이 없어
+   * `GET /me`의 `reconsentRequired`가 true다(첫 진입에서 `updateConsents()`로 받는다)
    */
   idp(provider: SocialProvider, options: {
     redirectUri: string;
+    agreements?: {
+      terms: true;
+      privacy: true;
+      marketing?: boolean;
+    };
   }): Promise<IdpStart>;
   /**
    * 소셜 로그인 마무리 — 돌아온 `code`를 구매자 토큰으로 바꾼다. state가 다르거나 구매자가 취소했으면
-   * `IdpCallbackError`. code는 1회용이고 1분 안에 바꿔야 한다
+   * `IdpCallbackError`. code는 1회용이고 1분 안에 바꿔야 한다. 약관 동의는 `idp()`에서 받는다
    */
   idpCallback(input: IdpCallbackInput & {
     error?: string | null;

package/dist/auth/index.mjs

@@ -1,4 +1,4 @@
-import { it as ApiError, t as createStorefrontClient } from "../client-D9iQIWnV.mjs";
+import { pt as ApiError, t as createStorefrontClient } from "../client-CHfCafer.mjs";
 //#region src/auth/index.ts
 /** 소셜 로그인 실패 — 구매자가 취소했거나(`access_denied`) state가 맞지 않는다 */
 var IdpCallbackError = class extends Error {
@@ -60,7 +60,11 @@ function createStorefrontAuth(options) {
 		/**
 		* 소셜 로그인 시작 — PKCE(S256)와 state를 만들고 공급자 로그인 주소를 받는다. 반환한 `state`·`codeVerifier`를
 		* 서버 세션에 보관하고 구매자를 `url`로 보낸다. 로그인을 마치면 `redirectUri`로 `?code=&state=`가 붙어 돌아온다.
-		* `redirectUri`는 스토어프론트 도메인 목록 안이어야 한다
+		* `redirectUri`는 스토어프론트 도메인 목록 안이어야 한다.
+		*
+		* 가입 화면에서 받은 약관 동의는 `agreements`로 함께 보낸다. **이 로그인으로 가입이 되는 경우에만** 이력에
+		* 남고(기존 회원의 로그인이면 무시한다), 보내지 않으면 가입은 되지만 필수 동의 이력이 없어
+		* `GET /me`의 `reconsentRequired`가 true다(첫 진입에서 `updateConsents()`로 받는다)
 		*/
 		async idp(provider, options) {
 			const state = randomToken(24);
@@ -68,7 +72,12 @@ function createStorefrontAuth(options) {
 			const { url } = await client().auth.idpAuthorize(provider, {
 				redirectUri: options.redirectUri,
 				codeChallenge: await s256(codeVerifier),
-				state
+				state,
+				agreements: options.agreements && {
+					terms: true,
+					privacy: true,
+					marketing: options.agreements.marketing ?? false
+				}
 			});
 			return {
 				url,
@@ -78,7 +87,7 @@ function createStorefrontAuth(options) {
 		},
 		/**
 		* 소셜 로그인 마무리 — 돌아온 `code`를 구매자 토큰으로 바꾼다. state가 다르거나 구매자가 취소했으면
-		* `IdpCallbackError`. code는 1회용이고 1분 안에 바꿔야 한다
+		* `IdpCallbackError`. code는 1회용이고 1분 안에 바꿔야 한다. 약관 동의는 `idp()`에서 받는다
 		*/
 		idpCallback(input) {
 			if (input.error) return Promise.reject(new IdpCallbackError(input.error));

package/dist/checkout-CHpxo2Ap.mjs

@@ -0,0 +1,310 @@
+import { z } from "zod";
+//#region src/schemas/checkout.ts
+const createCheckoutRequestSchema = z.object({
+	cartItemIds: z.array(z.string()).min(1).optional(),
+	directItem: z.object({
+		productId: z.string(),
+		optionId: z.string().optional(),
+		quantity: z.number().int().min(1)
+	}).optional()
+}).refine((value) => value.cartItemIds ? !value.directItem : !!value.directItem, { message: "cartItemIds와 directItem 중 하나만 전달해야 합니다" });
+/** 지역 추가 배송비 구분 — 우편번호로 판정한다 */
+const remoteAreaSchema = z.enum([
+	"NONE",
+	"JEJU",
+	"ISOLATED"
+]);
+/**
+* 배송비 내역 (이슈 #29) — 배송비를 **몇 번, 왜** 부과했는지다.
+*
+* 배송비는 **배송 묶음**마다 붙는다. 같은 출고지 + 같은 배송 정책인 상품은 한 묶음이고 한 번만 낸다.
+* 제주·도서산간 추가 배송비는 묶음마다 더하고, 무료배송이어도 붙는다.
+*
+* 주문서를 만들 때는 배송지를 모르므로 `zipCode`가 null이고 `remoteSurcharge`가 0이다.
+* 배송지를 입력하면 `POST /storefront/v1/checkout/{checkoutId}/delivery-quote`로 다시 받고,
+* **결제 시작이 보낸 배송지로 최종 확정한다** — 그래서 주문서 조회 금액과 실제 결제 금액이 다를 수 있다.
+*/
+const checkoutDeliverySchema = z.object({
+	baseFee: z.number().int().describe("기본 배송비 합계. 묶음마다 부과한 금액의 합이다"),
+	remoteSurcharge: z.number().int().describe("제주·도서산간 추가 배송비 합계. 묶음마다 붙는다. 배송지를 모르면 0"),
+	remoteArea: remoteAreaSchema.describe("배송지 지역 구분. 배송지를 모르면 NONE"),
+	remoteAreaLabel: z.string().nullable().describe("지역 안내 이름(예: 제주특별자치도). 추가 배송비 지역이 아니면 null"),
+	bundleCount: z.number().int().describe("배송 묶음 수 — 배송비를 부과한 횟수다"),
+	freeByThreshold: z.boolean().describe("스토어 전체 무료배송 기준액을 넘겨 기본 배송비를 면제했는가"),
+	zipCode: z.string().nullable().describe("이 금액에 반영한 배송지 우편번호. null이면 배송지 미반영(추가 배송비 0)이다")
+});
+const checkoutSessionSchema = z.object({
+	checkoutId: z.string(),
+	items: z.array(z.object({
+		productId: z.string(),
+		productName: z.string(),
+		/** variantId. 옵션 없는 상품은 default variant id */
+		optionId: z.string().nullable(),
+		optionName: z.string().nullable(),
+		quantity: z.number().int(),
+		unitPrice: z.number().int(),
+		totalPrice: z.number().int()
+	})),
+	amounts: z.object({
+		productAmount: z.number().int(),
+		deliveryFee: z.number().int(),
+		totalAmount: z.number().int()
+	}),
+	delivery: checkoutDeliverySchema.describe("배송비 내역. 배송지를 입력하면 금액이 바뀔 수 있다 — 최종 금액은 결제 시작 응답의 `amounts`다"),
+	expiresAt: z.string(),
+	paymentOptions: z.lazy(() => paymentOptionListSchema).describe("이 주문서에서 고를 수 있는 결제 옵션, PG 우선순위순. 셀러가 켠 PG·결제수단·간편결제만 담긴다. 비어 있으면 지금 결제할 수 없다"),
+	testPayment: z.boolean().describe("지금 결제하면 테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않아요 — 주문서에 테스트 결제 안내를 표시해요. 결제 요청 시점에 스토어 결제 설정으로 다시 정해지니 최종 값은 결제 요청 응답의 `testPayment`예요")
+});
+/**
+* 배송비 미리보기 요청 — 배송지 우편번호로 배송비를 다시 계산한다. 주문서를 바꾸지 않는다(읽기 계산이다).
+*
+* 구매자가 배송지를 입력하거나 고칠 때 부르면 제주·도서산간 추가 배송비가 반영된 금액을 미리 보여 줄 수 있다.
+*/
+const deliveryQuoteRequestSchema = z.object({ zipCode: z.string().regex(/^[0-9]{5}$/, "우편번호 5자리를 입력해 주세요").describe("배송지 우편번호 5자리") });
+/** 배송비 미리보기 응답 — 이 배송지로 결제하면 나갈 금액이다 */
+const deliveryQuoteSchema = z.object({
+	amounts: checkoutSessionSchema.shape.amounts.describe("이 배송지 기준 금액"),
+	delivery: checkoutDeliverySchema
+});
+const paymentMethodSchema = z.enum([
+	"CARD",
+	"BANK_TRANSFER",
+	"VIRTUAL_ACCOUNT",
+	"MOBILE",
+	"EASY_PAY"
+]);
+/** 결제를 처리하는 PG. 셀러가 직접 계약하고 콘솔 설정 › 결제에서 연결한다 */
+const pgProviderSchema = z.enum(["tosspayments", "portone"]);
+/** 간편결제사. 토스페이먼츠·포트원 모두 같은 코드를 쓴다 */
+const easyPayProviderSchema = z.enum([
+	"NAVERPAY",
+	"KAKAOPAY",
+	"TOSSPAY",
+	"PAYCO"
+]);
+/**
+* 응답에 실리는 간편결제사 — 서버가 간편결제사를 추가해도 파싱이 깨지지 않게 문자열로 받는다
+* (`pgProvider`·결제 상태와 같은 방식). 요청과 결제 옵션은 값을 골라 보내는 자리라 enum 그대로다.
+*/
+const easyPayProviderResponseSchema = z.string();
+const pg = pgProviderSchema.describe("결제를 처리할 PG");
+/**
+* 결제 옵션 — 어느 PG로 어떤 결제수단을 쓸지. `method`로 좁히면 필요한 필드가 타입으로 정해진다
+* (`EASY_PAY`만 `provider`가 있다). 주문서의 `paymentOptions` 항목을 그대로 넘기거나 직접 써도 된다.
+* 셀러가 켜지 않은 조합이면 서버가 409 `PAYMENT_OPTION_UNAVAILABLE`로 거절한다.
+*/
+const paymentOptionSchema = z.discriminatedUnion("method", [
+	z.object({
+		pg,
+		method: z.literal("CARD")
+	}),
+	z.object({
+		pg,
+		method: z.literal("EASY_PAY"),
+		provider: easyPayProviderSchema.describe("간편결제사 — 이 간편결제 결제창을 바로 연다")
+	}),
+	z.object({
+		pg,
+		method: z.literal("BANK_TRANSFER")
+	}),
+	z.object({
+		pg,
+		method: z.literal("VIRTUAL_ACCOUNT")
+	}),
+	z.object({
+		pg,
+		method: z.literal("MOBILE")
+	})
+]);
+/** 주문서가 내려주는 결제 옵션 — 결제 옵션 + 표시 이름 */
+const availablePaymentOptionSchema = paymentOptionSchema.and(z.object({
+	label: z.string().describe("결제수단 표시 이름 (예: 신용·체크카드, 네이버페이)"),
+	pgName: z.string().describe("PG 표시 이름 (예: 토스페이먼츠)")
+}));
+/**
+* 결제 옵션 목록 — 서버가 나중에 추가한 결제수단·PG를 이 SDK가 모르면 **그 항목만 빼고** 읽는다(목록 파싱은 깨지지 않는다).
+*
+* 모르는 항목을 버리는 일은 `preprocess`가 하고 항목 타입은 그대로 남는다 — OpenAPI 문서에 `items` 없는
+* 배열로 나가지 않게 하기 위해서다(`z.array(z.unknown()).transform(...)`은 출력 타입을 표현하지 못한다).
+*/
+const paymentOptionListSchema = z.preprocess((value) => Array.isArray(value) ? value.filter((item) => availablePaymentOptionSchema.safeParse(item).success) : value, z.array(availablePaymentOptionSchema));
+/** 결제 옵션을 화면 키로 — 라디오 value·React key. 예: `tosspayments:CARD`, `portone:EASY_PAY:NAVERPAY` */
+function paymentOptionKey(option) {
+	return option.method === "EASY_PAY" ? `${option.pg}:EASY_PAY:${option.provider}` : `${option.pg}:${option.method}`;
+}
+const shippingAddressInputSchema = z.object({
+	addressId: z.string().optional(),
+	receiverName: z.string().min(1, "수령인명을 입력해주세요").max(50),
+	phone: z.string().regex(/^01[0-9]{8,9}$/, "연락처 형식이 아닙니다 (예: 01012345678)"),
+	zipCode: z.string().regex(/^[0-9]{5}$/, "우편번호는 5자리 숫자입니다"),
+	address1: z.string().min(1, "기본 주소를 입력해주세요"),
+	address2: z.string().optional(),
+	deliveryMemo: z.string().max(100).optional(),
+	entranceCode: z.string().max(20).optional()
+});
+const guestInfoSchema = z.object({
+	name: z.string().min(1),
+	phone: z.string().regex(/^01[0-9]{8,9}$/),
+	email: z.email(),
+	orderPassword: z.string().min(6, "주문 조회 비밀번호는 6자 이상이어야 합니다")
+});
+/** 현금영수증을 신청할 수 있는 결제수단 — 계좌이체·가상계좌 */
+const CASH_RECEIPT_METHODS = ["BANK_TRANSFER", "VIRTUAL_ACCOUNT"];
+/** 이 결제수단으로 현금영수증을 신청할 수 있는가 */
+function cashReceiptAvailable(method) {
+	return CASH_RECEIPT_METHODS.includes(method);
+}
+/** 현금영수증 용도 — `INCOME_DEDUCTION` 소득공제(개인) · `EXPENSE_PROOF` 지출증빙(사업자) */
+const cashReceiptTypeSchema = z.enum(["INCOME_DEDUCTION", "EXPENSE_PROOF"]);
+/**
+* 주민등록번호·외국인등록번호 형식인가 — 현금영수증 식별 번호로는 받지 않는다.
+*
+* 현금영수증카드 번호의 아래 끝(13자리)이 주민등록번호 길이와 겹친다. 개인 식별 번호는 최소로 받는다는 원칙이라
+* 주민등록번호로 읽히는 값은 카드 번호 자리로도 받지 않는다.
+*
+* **13자리 숫자 전부를 막지 않는다.** 13자리 현금영수증카드를 쓰는 구매자가 신청할 수 없게 되기 때문이다.
+* 대신 주민등록번호 형식 — 생년월일 6자리(월 01~12, 일 01~31) + 성별·세기 코드(1~8, 5~8은 외국인등록번호) — 으로
+* 판정해 오탐을 줄인다(13자리 숫자 중 이 형식에 걸리는 비율은 약 3%다).
+*
+* 검증번호(뒤 1자리 mod 11)까지는 보지 않는다. 한 자리 오타가 난 주민등록번호도 생년월일을 담고 있어 막아야 하고,
+* 2020년 10월 이후 발급된 외국인등록번호에는 검증번호 규칙이 없다.
+*
+* `cashReceiptIdentityTypeOf`와 같이 하이픈·공백은 빼고 판정한다.
+*/
+function residentNumberLike(identityNumber) {
+	const digits = identityNumber.replace(/[\s-]/g, "");
+	if (!/^[0-9]{13}$/.test(digits)) return false;
+	const month = Number(digits.slice(2, 4));
+	const day = Number(digits.slice(4, 6));
+	const genderCode = Number(digits[6]);
+	return month >= 1 && month <= 12 && day >= 1 && day <= 31 && genderCode >= 1 && genderCode <= 8;
+}
+/**
+* 식별 번호 → 종류. 하이픈·공백은 빼고 판정한다. 용도에 맞지 않는 번호면 null이다.
+* - 소득공제: 휴대폰 번호(01로 시작하는 10~11자리) 또는 현금영수증카드 번호(13~19자리)
+* - 지출증빙: 사업자등록번호(10자리) 또는 현금영수증카드 번호(13~19자리)
+*
+* 자릿수 근거. PG 문서는 식별 번호의 최대 길이만 정하고 종류별 자릿수는 정하지 않는다
+* (토스페이먼츠 `customerIdentityNumber` "최대 길이는 30자", 소득공제는 휴대폰 번호·현금영수증카드 번호,
+* 지출증빙은 사업자등록번호: https://docs.tosspayments.com/common/apis/cash-receipt /
+* 포트원 V2는 종류만 PHONE·CARD·BUSINESS로 나눈다: https://developers.portone.io/api/rest-v2/payment.cashReceipt).
+* 그래서 자릿수는 국세청이 정하는 발급수단 규격을 따른다 — 홈택스 소비자 발급수단 등록의 카드 번호는
+* 13~19자리 숫자이고(https://thisthatbase.com/cash-receipts-card-registration/ 가 옮긴 홈택스 안내,
+* 원본은 https://www.hometax.go.kr/ 소비자 발급수단 관리), 사업자등록번호는 10자리, 휴대폰 번호는 01X + 7~8자리다.
+* 국세청 자진발급 번호(010-000-1234)도 휴대폰 형식으로 통과한다.
+*/
+function cashReceiptIdentityTypeOf(type, identityNumber) {
+	const digits = identityNumber.replace(/[\s-]/g, "");
+	if (!/^[0-9]+$/.test(digits)) return null;
+	if (residentNumberLike(digits)) return null;
+	if (/^[0-9]{13,19}$/.test(digits)) return "CARD";
+	if (type === "INCOME_DEDUCTION") return /^01[016789][0-9]{7,8}$/.test(digits) ? "PHONE" : null;
+	return /^[0-9]{10}$/.test(digits) ? "BUSINESS" : null;
+}
+/**
+* 현금영수증 신청 — 계좌이체·가상계좌 결제에서만 보낼 수 있다. 결제가 승인되면 sayren이 결제한 PG로 발급하고,
+* 환불하면 그만큼 취소한다. 식별 번호는 암호화해 저장하고 응답에는 가린 값만 나간다.
+*/
+const cashReceiptRequestSchema = z.object({
+	type: cashReceiptTypeSchema.describe("용도. `INCOME_DEDUCTION` 소득공제(개인) · `EXPENSE_PROOF` 지출증빙(사업자)"),
+	identityNumber: z.string().max(30).describe("식별 번호. 소득공제는 휴대폰 번호(01X + 7~8자리) 또는 현금영수증카드 번호(13~19자리), 지출증빙은 사업자등록번호(10자리) 또는 현금영수증카드 번호(13~19자리). 하이픈은 빼고 읽는다. 주민등록번호는 받지 않는다(`RESIDENT_NUMBER_NOT_ALLOWED`)")
+}).superRefine((value, ctx) => {
+	if (residentNumberLike(value.identityNumber)) {
+		ctx.addIssue({
+			code: "custom",
+			path: ["identityNumber"],
+			message: "주민등록번호는 현금영수증 식별 번호로 쓸 수 없어요. 휴대폰 번호 또는 현금영수증카드 번호를 입력해주세요 (RESIDENT_NUMBER_NOT_ALLOWED)"
+		});
+		return;
+	}
+	if (!cashReceiptIdentityTypeOf(value.type, value.identityNumber)) ctx.addIssue({
+		code: "custom",
+		path: ["identityNumber"],
+		message: value.type === "INCOME_DEDUCTION" ? "휴대폰 번호 또는 현금영수증카드 번호를 입력해주세요" : "사업자등록번호(10자리) 또는 현금영수증카드 번호를 입력해주세요"
+	});
+});
+const cashReceiptField = cashReceiptRequestSchema.optional().describe("현금영수증 신청. 계좌이체·가상계좌 옵션에서만 보낼 수 있다(그 밖의 옵션이면 400 `CASH_RECEIPT_NOT_AVAILABLE`). 결제가 승인되면 발급한다");
+/**
+* 결제 시작 — 배송지를 확정하고 고른 결제 옵션으로 결제 시도를 연다. 응답의 `payUrl`(결제 서비스)을 팝업(`mode=popup`)이나
+* 전체 페이지로 열면 결제 서비스가 PG 결제창을 띄우고 승인까지 한다. 리다이렉트 결제가 끝나면 구매자는 `returnUrl`로 돌아온다.
+* `returnUrl`의 도메인은 스토어 결제 도메인(콘솔 설정 › 결제)에 등록돼 있어야 한다(테스트 결제는 localhost 허용).
+*/
+const startPaymentRequestSchema = z.object({
+	option: paymentOptionSchema,
+	returnUrl: z.url().max(2048).describe("결제를 마치면 돌아올 스토어프론트 주소. 스토어 결제 도메인에 등록된 도메인이어야 한다"),
+	shippingAddress: shippingAddressInputSchema,
+	guest: guestInfoSchema.optional(),
+	cashReceipt: cashReceiptField
+});
+/**
+* 같은 결제에서 다른 결제 옵션으로 다시 시도. `returnUrl`을 생략하면 결제 시작 때의 복귀 주소를 쓴다.
+* `cashReceipt`를 보내면 현금영수증 신청을 이 값으로 바꾸고, 생략하면 결제 시작 때의 신청을 그대로 둔다
+* (승인된 결제수단이 계좌이체·가상계좌가 아니면 발급하지 않는다)
+*/
+const retryPaymentRequestSchema = z.object({
+	option: paymentOptionSchema,
+	returnUrl: startPaymentRequestSchema.shape.returnUrl.optional(),
+	cashReceipt: cashReceiptField
+});
+const paymentStartSchema = z.object({
+	paymentId: z.string().describe("결제 id. 상태 조회·재시도의 키다"),
+	attemptId: z.string().describe("결제 시도 id. PG 주문번호(토스 orderId, 포트원 paymentId)다"),
+	option: paymentOptionSchema.describe("이 시도의 결제 옵션"),
+	payUrl: z.string().describe("결제 서비스 주소. 팝업으로 열려면 쿼리 `mode=popup`을 붙이고, 그대로 이동하면 리다이렉트 결제다"),
+	expiresAt: z.string().describe("결제 요청 만료 시각"),
+	testPayment: z.boolean().describe("테스트 결제(샌드박스) 여부. true면 실제로 돈이 나가지 않는다 — 결제 화면에 테스트 결제 안내를 표시한다"),
+	amounts: checkoutSessionSchema.shape.amounts.describe("**확정 결제 금액** — 보낸 배송지로 배송비를 다시 계산한 값이다. 주문서 조회 시점의 `amounts`와 다를 수 있다(제주·도서산간 추가 배송비)"),
+	delivery: checkoutDeliverySchema.describe("확정 배송비 내역. `zipCode`는 보낸 배송지의 우편번호다")
+});
+/** 결제창에서 결제하지 못한 이유 */
+const paymentFailureCategorySchema = z.enum([
+	"PREPARE_FAILURE",
+	"DECLINED",
+	"USER_CANCELED"
+]);
+/**
+* 결제 상태 조회의 현재 상태 값 — 응답 스키마는 서버가 상태를 추가해도 파싱이 깨지지 않게 문자열로 받는다
+* (`pgProvider`와 같은 방식). 화면 분기는 이 목록으로 하고 모르는 값은 확인 중으로 다룬다.
+*/
+const PAYMENT_STATUS_VALUES = [
+	"pending",
+	"processing",
+	"completed",
+	"failed",
+	"expired"
+];
+/** 결제 결과 구분 — 결제 서비스가 스토어프론트에 돌려주는 값과 같다 */
+const PAYMENT_RESULT_VALUES = [
+	"COMPLETED",
+	"PROCESSING",
+	"CANCELED",
+	"FAILED",
+	"EXPIRED",
+	"PENDING"
+];
+const paymentStatusSchema = z.object({
+	paymentId: z.string(),
+	status: z.string().describe("결제 상태. 현재 값은 `pending` 결제 대기 · `processing` 승인 확인 중 · `completed` 결제 완료(주문 생성) · `failed` 실패 · `expired` 만료예요. 상태가 추가될 수 있어 문자열로 받아요 — 모르는 값은 `processing`처럼 다루고 계속 조회하세요"),
+	result: z.string().describe("화면 분기용 결과. `COMPLETED` 결제 완료 · `PROCESSING` 결과 확인 중 · `CANCELED` 구매자가 결제창을 닫음 · `FAILED` 결제 실패(다른 결제 옵션으로 재시도 가능) · `EXPIRED` 결제 요청 만료 · `PENDING` 결제 전이에요. 값이 추가될 수 있어 문자열로 받아요 — 모르는 값은 `PROCESSING`처럼 다루세요"),
+	orderId: z.string().nullable().describe("결제가 완료됐으면 주문 번호, 그 외에는 null"),
+	lastFailure: z.object({
+		attemptId: z.string(),
+		category: z.string().describe("`PREPARE_FAILURE`·`DECLINED`·`USER_CANCELED`(값이 추가될 수 있다)"),
+		code: z.string().nullable().describe("PG가 준 실패 코드. 내부 사유는 null이에요. 화면 분기는 `category`로 하세요"),
+		message: z.string().nullable().describe("구매자에게 보여 줄 안내 문구")
+	}).nullable().describe("현재 결제 시도가 실패·취소로 끝났으면 그 내용, 아니면 null"),
+	testPayment: z.boolean().describe("테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않았어요"),
+	expiresAt: z.string().describe("결제 요청 만료 시각")
+});
+/**
+* 결제 서비스가 팝업 opener에 보내는 메시지 — `type`으로 거르고 결과의 원천은 결제 상태 조회다.
+* 안내 문구는 싣지 않는다. 화면 문구는 상태 조회의 `lastFailure`를 쓴다
+*/
+const paymentMessageSchema = z.object({
+	type: z.literal("sayren:payment"),
+	paymentId: z.string(),
+	result: z.string(),
+	orderId: z.string().optional()
+});
+//#endregion
+export { startPaymentRequestSchema as A, paymentStartSchema as C, residentNumberLike as D, remoteAreaSchema as E, retryPaymentRequestSchema as O, paymentOptionSchema as S, pgProviderSchema as T, paymentFailureCategorySchema as _, cashReceiptAvailable as a, paymentOptionKey as b, cashReceiptTypeSchema as c, createCheckoutRequestSchema as d, deliveryQuoteRequestSchema as f, guestInfoSchema as g, easyPayProviderSchema as h, availablePaymentOptionSchema as i, shippingAddressInputSchema as k, checkoutDeliverySchema as l, easyPayProviderResponseSchema as m, PAYMENT_RESULT_VALUES as n, cashReceiptIdentityTypeOf as o, deliveryQuoteSchema as p, PAYMENT_STATUS_VALUES as r, cashReceiptRequestSchema as s, CASH_RECEIPT_METHODS as t, checkoutSessionSchema as u, paymentMessageSchema as v, paymentStatusSchema as w, paymentOptionListSchema as x, paymentMethodSchema as y };

package/dist/{client-D9iQIWnV.mjs → client-CHfCafer.mjs}

@@ -1,5 +1,5 @@
 import { a as ANALYTICS_VISITOR_HEADER, r as ANALYTICS_SESSION_HEADER } from "./analytics-CgD70OqH.mjs";
-import { a as createCheckoutRequestSchema, b as startPaymentRequestSchema, d as paymentMethodSchema, g as paymentStatusSchema, h as paymentStartSchema, i as checkoutSessionSchema, o as easyPayProviderResponseSchema, v as retryPaymentRequestSchema } from "./checkout-JFk3b8RG.mjs";
+import { A as startPaymentRequestSchema, C as paymentStartSchema, O as retryPaymentRequestSchema, d as createCheckoutRequestSchema, f as deliveryQuoteRequestSchema, m as easyPayProviderResponseSchema, p as deliveryQuoteSchema, u as checkoutSessionSchema, w as paymentStatusSchema, y as paymentMethodSchema } from "./checkout-CHpxo2Ap.mjs";
 import { z } from "zod";
 //#region src/http.ts
 /** 표준 엔벨로프의 $.error 상세 */
@@ -177,6 +177,18 @@ const socialProviderSchema = z.enum([
 	"naver",
 	"google"
 ]);
+/**
+* 소셜 가입 화면에서 받은 필수·선택 동의 — 공급자로 보내기 전에 함께 보낸다.
+*
+* **이 흐름으로 회원이 처음 만들어질 때만 쓴다.** 이미 있는 회원의 로그인이면 무시한다(동의는 늘어나지 않는다).
+* 보내지 않으면 필수 동의 이력이 남지 않아 `GET /me`의 `reconsentRequired`가 true가 되고,
+* 스토어프론트가 첫 진입에서 `POST /me/consents`로 받는다(가입 자체는 거부하지 않는다).
+*/
+const idpAgreementsSchema = z.object({
+	terms: z.literal(true),
+	privacy: z.literal(true),
+	marketing: z.boolean().default(false)
+});
 /** `POST /auth/idp/{provider}/authorize` 본문 — PKCE(S256)와 state는 SDK가 만든다 */
 const idpAuthorizeRequestSchema = z.object({
 	/** 로그인을 마치고 돌아올 스토어프론트 주소. 스토어프론트 도메인 목록 안이어야 한다 */
@@ -184,7 +196,9 @@ const idpAuthorizeRequestSchema = z.object({
 	/** base64url(SHA-256(codeVerifier)) */
 	codeChallenge: z.string().regex(/^[A-Za-z0-9_-]{43}$/),
 	/** 스토어프론트가 만든 값 — 돌아올 때 그대로 붙어 온다. 세션에 저장해 두고 비교한다 */
-	state: z.string().min(16).max(128)
+	state: z.string().min(16).max(128),
+	/** 가입이 되는 경우 남길 동의. 기존 회원 로그인이면 무시한다 */
+	agreements: idpAgreementsSchema.optional()
 });
 const idpAuthorizeResponseSchema = z.object({ 
 /** 구매자를 보낼 공급자 로그인 주소 */
@@ -384,13 +398,31 @@ const createClaimRequestSchema = z.object({
 	reason: claimReasonSchema,
 	reasonDetail: z.string().max(1e3).optional(),
 	evidenceImages: z.array(z.url()).max(5).optional(),
-	exchangeOptionId: z.string().optional()
+	exchangeOptionId: z.string().optional(),
+	quantity: z.number().int().min(1).optional().describe("취소·반품·교환할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`")
 });
 const createClaimResultSchema = z.object({
 	claimId: z.string(),
 	status: z.literal("REQUESTED"),
-	expectedRefundAmount: z.number().int().nullable(),
-	claimDeliveryFee: z.number().int()
+	expectedRefundAmount: z.number().int().nullable().describe("예상 환불액 — 수량 비율 상품 금액 − 반품 배송비. **배송비 환불은 여기 포함되지 않고 `deliveryFeeRefundAmount`로 따로 온다**(승인 시점의 배송 묶음 상태로 확정되기 때문이다). 교환은 환불이 없어 null이다"),
+	claimDeliveryFee: z.number().int().describe("구매자가 부담하는 반품·교환 배송비. 원 단위"),
+	quantity: z.number().int().describe("접수된 수량. 요청에서 생략하면 남은 수량 전체다"),
+	deliveryFeeRefundAmount: z.number().int().describe("환불 예정 배송비. 배송 묶음이 모두 취소되거나 판매자 귀책일 때만 0보다 크다")
+});
+/**
+* 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+* 상품이 반품지를 따로 지정했으면 그 주소다.
+*
+* 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+* 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+*/
+const claimReturnAddressSchema = z.object({
+	name: z.string().describe("주소 이름(셀러가 붙인 별칭). 예: 본사 물류센터"),
+	contactName: z.string().describe("수취인 이름"),
+	phone: z.string().describe("연락처"),
+	zipCode: z.string(),
+	address1: z.string(),
+	address2: z.string().nullable()
 });
 const myClaimSchema = z.object({
 	claimId: z.string(),
@@ -398,13 +430,77 @@ const myClaimSchema = z.object({
 	status: claimStatusSchema,
 	orderItemId: z.string(),
 	productName: z.string(),
+	quantity: z.number().int().describe("접수된 수량"),
 	reason: z.string(),
-	expectedRefundAmount: z.number().int().nullable(),
+	expectedRefundAmount: z.number().int().nullable().describe("예상 환불액 — 수량 비율 상품 금액 − 반품 배송비 − 조건부 무료배송 미달 차감. **배송비 환불은 포함되지 않고 `expectedDeliveryFeeRefundAmount`로 따로 온다.** 교환은 null이다"),
+	expectedDeliveryFeeRefundAmount: z.number().int().nullable().describe("예상 배송비 환불액. 배송 묶음이 모두 취소되거나 판매자 귀책일 때만 0보다 크다. 이 필드가 생기기 전에 접수된 클레임은 null이다"),
 	rejectReason: z.string().nullable(),
+	returnAddress: claimReturnAddressSchema.nullable().describe("반품·교환 물건을 보낼 반품지(이슈 #30). 직접 보내는 수거 안내에 쓴다. 취소 클레임은 null"),
 	requestedAt: z.string(),
 	completedAt: z.string().nullable()
 });
 //#endregion
+//#region src/schemas/consent.ts
+/**
+* 동의 종류 — 이용약관(`TERMS`)·개인정보 수집이용(`PRIVACY`)은 가입 필수, 마케팅 수신(`MARKETING`)은 선택이다.
+* 필수 동의는 철회할 수 없다(철회 = 탈퇴).
+*/
+const consentKindSchema = z.enum([
+	"TERMS",
+	"PRIVACY",
+	"MARKETING"
+]);
+/** 동의 이력의 한 줄이 무엇인가 — 동의했거나 철회했다 */
+const consentActionSchema = z.enum(["AGREED", "WITHDRAWN"]);
+/**
+* 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
+* `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
+* `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
+*/
+const consentSourceSchema = z.enum([
+	"SIGNUP",
+	"SOCIAL_SIGNUP",
+	"DELEGATED",
+	"RECONSENT",
+	"MEMBER_UPDATE",
+	"SELLER"
+]);
+/** 종류별 현재 동의 상태 */
+const consentStateSchema = z.object({
+	kind: consentKindSchema,
+	agreed: z.boolean(),
+	/** 동의한 약관 버전. 마케팅은 버전이 없어 null이고, 동의 이력이 없으면 null이다 */
+	agreedVersion: z.string().nullable(),
+	/** 스토어의 현재 약관 버전. 마케팅은 null */
+	currentVersion: z.string().nullable(),
+	/**
+	* 스토어가 정한 현재 약관 문서 주소. 재동의 화면에서 이 주소를 보여 준다.
+	* 스토어가 정하지 않았거나 마케팅이면 null이다(동의한 시점의 주소는 셀러가 보는 이력에 남는다).
+	*/
+	currentDocumentUrl: z.string().nullable(),
+	/** 마지막으로 동의·철회한 시각. 이력이 없으면 null */
+	updatedAt: z.string().nullable(),
+	/** 약관이 개정돼 다시 받아야 하는가. 마케팅은 항상 false */
+	reconsentRequired: z.boolean()
+});
+/** `GET /storefront/v1/me/consents` 응답 */
+const memberConsentsSchema = z.object({
+	terms: consentStateSchema,
+	privacy: consentStateSchema,
+	marketing: consentStateSchema,
+	/** 필수 동의 중 하나라도 다시 받아야 하면 true — `POST /me/consents`로 받는다 */
+	reconsentRequired: z.boolean()
+});
+/**
+* `POST /storefront/v1/me/consents` 본문 — 바꿀 항목만 보낸다.
+* 필수 동의는 동의(`true`)만 보낼 수 있다. 이미 현재 버전에 동의한 항목은 이력을 더 남기지 않는다.
+*/
+const consentUpdateRequestSchema = z.object({
+	terms: z.literal(true).optional().describe("이용약관 재동의"),
+	privacy: z.literal(true).optional().describe("개인정보 수집이용 재동의"),
+	marketing: z.boolean().optional().describe("마케팅 수신 동의(false면 철회)")
+}).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 항목이 필요합니다" });
+//#endregion
 //#region src/schemas/customer-inquiry.ts
 const customerInquiryCategorySchema = z.enum([
 	"DELIVERY",
@@ -466,7 +562,8 @@ const memberSchema = z.object({
 	phone: z.string().nullable(),
 	point: z.number().int(),
 	marketingAgreed: z.boolean(),
-	joinedAt: z.string()
+	joinedAt: z.string(),
+	reconsentRequired: z.boolean().describe("약관이 개정돼 필수 동의를 다시 받아야 하는가. true면 `GET /me/consents`로 어떤 항목인지 확인하고 `POST /me/consents`로 받는다. 받기 전에도 스토어 이용은 막히지 않는다")
 });
 const updateProfileRequestSchema = z.object({
 	name: z.string().max(50).optional(),
@@ -505,7 +602,9 @@ const myOrderItemSchema = z.object({
 	productName: z.string(),
 	thumbnailUrl: z.url().nullable().describe("주문 시점의 대표 이미지. 없었으면 null"),
 	optionName: z.string().nullable(),
-	quantity: z.number().int(),
+	quantity: z.number().int().describe("주문 수량"),
+	canceledQuantity: z.number().int().describe("취소·반품으로 환불된 누적 수량. 부분 취소가 없었으면 0이다"),
+	activeQuantity: z.number().int().describe("남은 수량 (`quantity` − `canceledQuantity`). 취소·반품·교환 요청 수량의 상한이다"),
 	totalPrice: z.number().int(),
 	status: orderItemStatusSchema,
 	claimStatus: z.string().nullable(),
@@ -539,6 +638,11 @@ const myOrderSchema = z.object({
 	}),
 	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 나가지 않았어요 — 주문 화면에 테스트 결제 배지를 표시해요")
 });
+/**
+* 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+* `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+*/
+const trackingStageResponseSchema = z.string();
 const deliveryTrackingSchema = z.object({
 	carrierName: z.string(),
 	trackingNumber: z.string(),
@@ -549,10 +653,13 @@ const deliveryTrackingSchema = z.object({
 		"DELIVERED"
 	]),
 	trackingEvents: z.array(z.object({
-		status: z.string(),
-		location: z.string(),
-		occurredAt: z.string()
-	}))
+		status: z.string().describe("택배사가 알려 준 처리 내용(예: 집화처리, 배송출발)"),
+		location: z.string().describe("처리 장소. 모르면 빈 문자열"),
+		occurredAt: z.string(),
+		stage: trackingStageResponseSchema.nullable().optional().default(null).describe("이 이벤트의 추적 단계. 배달 실패처럼 단계로 나눌 수 없는 이벤트는 null. 서버는 항상 싣는다. 현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 값이 추가될 수 있어 문자열로 받는다")
+	})).describe("배송 추적 이력. 시각 오름차순(오래된 것부터)"),
+	trackingStage: trackingStageResponseSchema.nullable().optional().default(null).describe("현재 추적 단계. 택배 발송이 아니거나, 아직 조회되지 않았거나, 택배사 전산에 송장이 없으면 null. 서버는 항상 싣는다. 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·`OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)이고 값이 추가될 수 있어 문자열로 받는다"),
+	trackingCheckedAt: z.string().nullable().optional().default(null).describe("택배사에서 추적 정보를 마지막으로 받아 온 시각(ISO 8601). 받아 온 적이 없으면 null. 서버는 항상 싣는다")
 });
 /** `POST /me/order-items/{orderItemId}/purchase-decision` 응답 */
 const purchaseDecisionResultSchema = z.object({
@@ -722,6 +829,16 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 		checkout: {
 			create: (body) => http.request("POST", "/checkout", checkoutSessionSchema, { body: createCheckoutRequestSchema.parse(body) }),
 			/**
+			* `POST /checkout/{checkoutId}/delivery-quote` — 배송비 미리보기. 배송지 우편번호로 배송비를 다시 계산한다.
+			*
+			* 주문서를 만들 때는 배송지를 모르므로 제주·도서산간 추가 배송비가 빠져 있다. 구매자가 배송지를 입력하거나
+			* 고칠 때 이 메서드로 금액을 갱신하면 결제 직전에 금액이 바뀌는 일을 피할 수 있다. 주문서를 바꾸지 않는
+			* 읽기 계산이고, **최종 금액은 결제 시작 응답의 `amounts`다.**
+			*
+			* 에러(`ApiError.code`): 404 `CHECKOUT_NOT_FOUND`, 409 `CHECKOUT_EXPIRED`, 409 `ALREADY_PAID`
+			*/
+			quoteDelivery: (checkoutId, body) => http.request("POST", path`/checkout/${checkoutId}/delivery-quote`, deliveryQuoteSchema, { body: deliveryQuoteRequestSchema.parse(body) }),
+			/**
 			* `POST /checkout/{checkoutId}/payment` — 결제 시작. 배송지와 결제 옵션(`paymentOptions` 항목 또는 직접 쓴 옵션)으로
 			* 결제 세션·첫 시도를 만들고 결제 서비스 주소(`payUrl`)를 돌려준다. 그 주소를 열어 결제를 진행하는 것은
 			* `@sayren/storefront-sdk/payments`의 `createPayments().start()`다 — 이 메서드는 값만 받는다.
@@ -765,6 +882,10 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 		member: {
 			me: () => http.request("GET", "/me", memberSchema),
 			updateMe: (body) => http.requestVoid("PATCH", "/me", { body: updateProfileRequestSchema.parse(body) }),
+			/** 약관·개인정보·마케팅 동의의 현재 상태와 재동의 필요 여부 */
+			consents: () => http.request("GET", "/me/consents", memberConsentsSchema),
+			/** 재동의·마케팅 동의 변경 — 바꾼 뒤의 상태를 돌려준다 */
+			updateConsents: (body) => http.request("POST", "/me/consents", memberConsentsSchema, { body: consentUpdateRequestSchema.parse(body) }),
 			listAddresses: () => http.request("GET", "/me/addresses", z.array(memberAddressSchema)),
 			createAddress: (body) => http.requestVoid("POST", "/me/addresses", { body: memberAddressRequestSchema.parse(body) }),
 			updateAddress: (addressId, body) => http.requestVoid("PUT", path`/me/addresses/${addressId}`, { body: memberAddressRequestSchema.parse(body) }),
@@ -788,4 +909,4 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 	};
 }
 //#endregion
-export { signupRequestSchema as $, createClaimResultSchema as A, pageInfoSchema as B, publicInquirySchema as C, claimReasonSchema as D, customerInquirySchema as E, productFacetsSchema as F, updateCartItemRequestSchema as G, addCartItemRequestSchema as H, productPageSchema as I, idpAuthorizeResponseSchema as J, anonymousSessionSchema as K, productSortSchema as L, categoryNodeSchema as M, productCardSchema as N, claimTypeSchema as O, productDetailSchema as P, memberIdentitiesSchema as Q, claimStatusSchema as R, createInquiryResultSchema as S, customerInquiryCategorySchema as T, cartItemSchema as U, pageSchema as V, cartSchema as W, linkIdentityRequestSchema as X, idpTokenRequestSchema as Y, loginRequestSchema as Z, memberAddressSchema as _, publicReviewSchema as a, buildQuery as at, wishlistAddResultSchema as b, updateReviewRequestSchema as c, deliveryTrackingSchema as d, socialProviderSchema as et, myOrderItemSchema as f, memberAddressRequestSchema as g, purchaseDecisionResultSchema as h, createReviewResultSchema as i, ApiError as it, myClaimSchema as j, createClaimRequestSchema as k, updateReviewResultSchema as l, orderShippingAddressSchema as m, storefrontStoreSchema as n, withdrawRequestSchema as nt, reviewPageSchema as o, toApiError as ot, myOrderSchema as p, idpAuthorizeRequestSchema as q, createReviewRequestSchema as r, withdrawalBlockedDetailsSchema as rt, reviewSummarySchema as s, unwrapData as st, createStorefrontClient as t, tokenPairSchema as tt, writableReviewSchema as u, memberSchema as v, createCustomerInquiryRequestSchema as w, createInquiryRequestSchema as x, updateProfileRequestSchema as y, orderItemStatusSchema as z };
+export { updateCartItemRequestSchema as $, consentSourceSchema as A, categoryNodeSchema as B, createInquiryResultSchema as C, customerInquirySchema as D, customerInquiryCategorySchema as E, claimReturnAddressSchema as F, productSortSchema as G, productDetailSchema as H, claimTypeSchema as I, pageInfoSchema as J, claimStatusSchema as K, createClaimRequestSchema as L, consentUpdateRequestSchema as M, memberConsentsSchema as N, consentActionSchema as O, claimReasonSchema as P, cartSchema as Q, createClaimResultSchema as R, createInquiryRequestSchema as S, createCustomerInquiryRequestSchema as T, productFacetsSchema as U, productCardSchema as V, productPageSchema as W, addCartItemRequestSchema as X, pageSchema as Y, cartItemSchema as Z, memberAddressRequestSchema as _, publicReviewSchema as a, linkIdentityRequestSchema as at, updateProfileRequestSchema as b, updateReviewRequestSchema as c, signupRequestSchema as ct, deliveryTrackingSchema as d, withdrawRequestSchema as dt, anonymousSessionSchema as et, myOrderItemSchema as f, withdrawalBlockedDetailsSchema as ft, trackingStageResponseSchema as g, unwrapData as gt, purchaseDecisionResultSchema as h, toApiError as ht, createReviewResultSchema as i, idpTokenRequestSchema as it, consentStateSchema as j, consentKindSchema as k, updateReviewResultSchema as l, socialProviderSchema as lt, orderShippingAddressSchema as m, buildQuery as mt, storefrontStoreSchema as n, idpAuthorizeRequestSchema as nt, reviewPageSchema as o, loginRequestSchema as ot, myOrderSchema as p, ApiError as pt, orderItemStatusSchema as q, createReviewRequestSchema as r, idpAuthorizeResponseSchema as rt, reviewSummarySchema as s, memberIdentitiesSchema as st, createStorefrontClient as t, idpAgreementsSchema as tt, writableReviewSchema as u, tokenPairSchema as ut, memberAddressSchema as v, publicInquirySchema as w, wishlistAddResultSchema as x, memberSchema as y, myClaimSchema as z };