@sayren/storefront-sdk 0.12.0 → 0.14.0

package/dist/auth/index.mjs

@@ -1,4 +1,4 @@
-import { pt as ApiError, t as createStorefrontClient } from "../client-DkyvDLXK.mjs";
+import { ft as ApiError, t as createStorefrontClient } from "../client-CUF2xGu8.mjs";
 //#region src/auth/index.ts
 /** 소셜 로그인 실패 — 구매자가 취소했거나(`access_denied`) state가 맞지 않는다 */
 var IdpCallbackError = class extends Error {

package/dist/{checkout-BeZKjYJz.mjs → checkout-wrCpR-P1.mjs}

@@ -1,4 +1,152 @@
 import { z } from "zod";
+//#region src/schemas/common.ts
+const pageInfoSchema = z.object({
+	page: z.number().int(),
+	size: z.number().int(),
+	totalElements: z.number().int(),
+	totalPages: z.number().int()
+});
+function pageSchema(item) {
+	return pageInfoSchema.extend({ contents: z.array(item) });
+}
+const orderItemStatusSchema = z.enum([
+	"PAYMENT_WAITING",
+	"PAID",
+	"CONFIRMED",
+	"DISPATCHED",
+	"DELIVERING",
+	"DELIVERED",
+	"PURCHASE_DECIDED",
+	"CANCELED"
+]);
+const claimStatusSchema = z.enum([
+	"REQUESTED",
+	"HELD",
+	"COLLECTING",
+	"COLLECTED",
+	"REDELIVERING",
+	"APPROVED",
+	"REJECTED",
+	"COMPLETED",
+	"WITHDRAWN"
+]);
+/**
+* 상품 유형 (이슈 #48). 응답에서는 문자열로 받는다(값이 추가될 수 있다). 현재 값은 `SHIPPING`(배송 상품)·
+* `DOWNLOAD`(파일 다운로드)·`CODE`(코드 발급)·`SERVICE`(이용권·서비스)·`PICKUP`(방문 수령)이다.
+* 이 필드 이전 서버의 응답에는 없어 `SHIPPING`으로 읽는다. 서버는 항상 싣는다.
+*/
+const fulfillmentTypeField = () => z.string().optional().default("SHIPPING").describe("상품 유형. 현재 값은 `SHIPPING`(배송 상품)·`DOWNLOAD`(파일 다운로드)·`CODE`(코드 발급)·`SERVICE`(이용권·서비스)·`PICKUP`(방문 수령)이고 값이 추가될 수 있어 문자열로 받는다. 서버는 항상 싣는다");
+/**
+* 배송 필요 여부 (이슈 #48). false면 배송지를 받지 않는다. 이 필드 이전 서버의 응답에는 없어 true로 읽는다.
+*/
+const requiresShippingField = (description) => z.boolean().optional().default(true).describe(`${description} 서버는 항상 싣는다`);
+/** 배송이 필요한 상품 유형인가 — 배송 상품(`SHIPPING`)만 택배 배송이 있다. 모르는 값은 배송 상품으로 본다 */
+function isShippingFulfillment(fulfillmentType) {
+	return fulfillmentType === void 0 || fulfillmentType === null || ![
+		"DOWNLOAD",
+		"CODE",
+		"SERVICE",
+		"PICKUP"
+	].includes(fulfillmentType);
+}
+//#endregion
+//#region src/schemas/coupon.ts
+/**
+* 스토어프론트 쿠폰 계약 (이슈 #47).
+*
+* 구매자는 주문서에서 쿠폰을 고르거나 코드를 입력한다. 금액 미리보기(`POST /checkout/{checkoutId}/pricing`)는
+* 주문서를 바꾸지 않는 읽기 계산이고, **확정은 결제 시작(`coupons` 필드)만 한다** — 결제 시작이 쿠폰을 예약하고 그 금액으로
+* 결제 금액을 정한다. 결제가 실패하거나 만료되면 예약이 풀려 같은 쿠폰을 다시 쓸 수 있다.
+*
+* 한 주문에 주문 쿠폰 1장, 주문상품 한 줄에 상품 쿠폰 1장까지다. 같은 쿠폰을 두 번 쓸 수 없다.
+*/
+/** 적용할 쿠폰 한 장 — 발급 쿠폰 id 또는 코드 중 하나 */
+const couponApplicationSchema = z.object({
+	issueId: z.string().min(1).optional().describe("내 쿠폰(발급 쿠폰) id — `GET /me/coupons`의 `issueId`"),
+	code: z.string().trim().min(1).max(30).optional().describe("쿠폰 코드. 대소문자를 구분하지 않는다"),
+	optionId: z.string().optional().describe("상품 쿠폰을 걸 주문서 항목의 `optionId`. 생략하면 할인이 가장 큰 항목에 건다. 주문 쿠폰에는 쓰지 않는다")
+}).refine((value) => (value.issueId ? 1 : 0) + (value.code ? 1 : 0) === 1, { message: "issueId와 code 중 하나만 보내 주십시오" });
+/** 한 번에 적용할 수 있는 쿠폰 수 */
+const MAX_COUPONS_PER_CHECKOUT = 5;
+const couponApplicationListSchema = z.array(couponApplicationSchema).max(5).describe("적용할 쿠폰. 주문 쿠폰 1장, 주문상품 한 줄에 상품 쿠폰 1장까지 함께 쓴다");
+/** 쿠폰 혜택 — 응답 표시용. 값이 늘 수 있어 방식은 문자열이다 */
+const couponBenefitViewSchema = z.object({
+	type: z.string().describe("할인 방식. 현재 값은 `RATE`(정률 %)·`AMOUNT`(정액 원)"),
+	value: z.number().int().describe("정률이면 %, 정액이면 원"),
+	maxDiscountAmount: z.number().int().nullable().describe("정률 할인의 최대 할인액. 없으면 null")
+});
+/** 쿠폰 한 장의 적용 결과 */
+const couponResultSchema = z.object({
+	couponId: z.string(),
+	issueId: z.string().nullable().describe("발급 쿠폰 id. 코드로 적용했으면 null"),
+	code: z.string().nullable().describe("코드로 적용했으면 그 코드(대문자). 그 밖은 null"),
+	name: z.string(),
+	kind: z.string().describe("쿠폰 종류. 현재 값은 `ORDER`(주문 쿠폰)·`PRODUCT`(상품 쿠폰)"),
+	benefit: couponBenefitViewSchema,
+	applied: z.boolean(),
+	discountAmount: z.number().int().describe("이 쿠폰의 할인액. 적용하지 못했으면 0"),
+	rejectReason: z.string().nullable().describe("적용하지 못한 사유. `MIN_ORDER_AMOUNT`(최소 주문 금액 미달)·`NO_ELIGIBLE_ITEMS`(대상 상품 없음)·`NOT_STARTED`·`EXPIRED`·`MEMBER_ONLY`(회원 전용)·`STACK_LIMIT`(같은 종류 쿠폰이 이미 적용됨)·`DUPLICATE_COUPON`·`LINE_NOT_ELIGIBLE`·`NO_DISCOUNT`·`IN_USE`(다른 결제에서 쓰는 중)·`LIMIT_REACHED`(1인 사용 한도)·`EXHAUSTED`(총 사용 한도)·`INACTIVE`(중지된 쿠폰). 값이 늘 수 있다"),
+	optionId: z.string().nullable().describe("상품 쿠폰이 걸린 주문서 항목의 `optionId`. 그 밖은 null")
+});
+/** 쿠폰을 반영한 금액 — 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount */
+const pricingAmountsSchema = z.object({
+	productAmount: z.number().int(),
+	deliveryFee: z.number().int(),
+	couponDiscountAmount: z.number().int(),
+	deliveryDiscountAmount: z.number().int(),
+	totalAmount: z.number().int().describe("결제 금액")
+});
+/** `POST /checkout/{checkoutId}/pricing` 요청 */
+const checkoutPricingRequestSchema = z.object({
+	zipCode: z.string().regex(/^[0-9]{5}$/, "우편번호 5자리를 입력해 주십시오").optional().describe("배송지 우편번호. 주면 제주·도서산간 추가 배송비까지 반영한다"),
+	coupons: couponApplicationListSchema
+});
+/** 결제 금액의 하한 — 쿠폰 적용 뒤 결제 금액이 이보다 작으면 결제를 시작할 수 없다 */
+const MIN_PAYMENT_AMOUNT = 100;
+const checkoutPricingSchema = z.object({
+	amounts: pricingAmountsSchema,
+	coupons: z.array(couponResultSchema).describe("요청한 쿠폰마다 한 줄, 요청 순서대로"),
+	items: z.array(z.object({
+		optionId: z.string().nullable(),
+		couponDiscountAmount: z.number().int().describe("이 항목에 들어간 쿠폰 할인")
+	})).describe("주문서 항목별 쿠폰 할인 — 주문서 `items`와 같은 순서"),
+	payable: z.boolean().describe("이 금액으로 결제를 시작할 수 있는가 — 적용하지 못한 쿠폰이 있거나 결제 금액이 100원 미만이면 false")
+});
+/** `GET /checkout/{checkoutId}/coupons` 항목 — 이 주문서에 쓸 수 있는 내 쿠폰 */
+const applicableCouponSchema = z.object({
+	issueId: z.string(),
+	couponId: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+	kind: z.string(),
+	benefit: couponBenefitViewSchema,
+	minOrderAmount: z.number().int(),
+	validUntil: z.string().nullable().describe("유효 기간 끝(이 시각부터 못 쓴다). 없으면 null"),
+	applicable: z.boolean().describe("이 주문서에 혼자 적용하면 할인이 되는가"),
+	expectedDiscountAmount: z.number().int().describe("혼자 적용했을 때의 예상 할인액"),
+	rejectReason: z.string().nullable().describe("적용할 수 없는 사유(`couponResultSchema.rejectReason`과 같은 값)")
+});
+/** `GET /me/coupons` 항목 */
+const myCouponSchema = z.object({
+	issueId: z.string(),
+	couponId: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+	kind: z.string(),
+	benefit: couponBenefitViewSchema,
+	minOrderAmount: z.number().int(),
+	status: z.string().describe("상태. 현재 값은 `AVAILABLE`(사용 가능)·`RESERVED`(결제 중)·`USED`(사용함)·`EXPIRED`(기간 지남)이고 값이 늘 수 있다"),
+	validFrom: z.string(),
+	validUntil: z.string().nullable(),
+	usedOrderId: z.string().nullable(),
+	issuedAt: z.string()
+});
+const myCouponListQuerySchema = z.object({ status: z.enum([
+	"available",
+	"used",
+	"expired"
+]).optional().describe("`available`=사용 가능(결제 중 포함), `used`=사용함, `expired`=기간 지남. 생략하면 전부") });
+//#endregion
 //#region src/schemas/checkout.ts
 const createCheckoutRequestSchema = z.object({
 	cartItemIds: z.array(z.string()).min(1).optional(),
@@ -48,9 +196,19 @@ const checkoutSessionSchema = z.object({
 	amounts: z.object({
 		productAmount: z.number().int(),
 		deliveryFee: z.number().int(),
-		totalAmount: z.number().int()
+		totalAmount: z.number().int(),
+		couponDiscountAmount: z.number().int().optional().default(0).describe("쿠폰 할인(상품·주문 쿠폰). 주문서는 쿠폰 전이라 0이고, 결제 시작 응답은 적용한 쿠폰의 할인이다"),
+		deliveryDiscountAmount: z.number().int().optional().default(0).describe("배송비 쿠폰 할인. 쿠폰이 없으면 0")
 	}),
 	delivery: checkoutDeliverySchema.describe("배송비 내역. 배송지를 입력하면 금액이 바뀔 수 있다 — 최종 금액은 결제 시작 응답의 `amounts`다"),
+	requiresShipping: requiresShippingField("택배 배송이 필요한 상품이 있는가. false면 배송지를 받지 않는다 — 결제 시작에 `shippingAddress`를 보내지 않아도 된다."),
+	withdrawal: z.object({
+		required: z.boolean().describe("청약철회 제한 상품(제공이 시작되면 취소·반품할 수 없는 파일·코드·이용권)이 있는가. true면 `notice`를 결제 전에 보여 주고 동의를 받아 결제 시작에 `withdrawalAgreement: true`를 보낸다"),
+		notice: z.string().nullable().describe("구매자에게 보여 줄 고지 문구. `required`가 false면 null")
+	}).optional().default({
+		required: false,
+		notice: null
+	}).describe("청약철회 제한 고지(이슈 #48). 서버는 항상 싣는다"),
 	expiresAt: z.string(),
 	paymentOptions: z.lazy(() => paymentOptionListSchema).describe("이 주문서에서 고를 수 있는 결제 옵션, PG 우선순위순. 셀러가 켠 PG·결제수단·간편결제만 담긴다. 비어 있으면 지금 결제할 수 없다"),
 	testPayment: z.boolean().describe("지금 결제하면 테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않습니다 — 주문서에 테스트 결제 안내를 표시합니다. 결제 요청 시점에 스토어 결제 설정으로 다시 정해지니 최종 값은 결제 요청 응답의 `testPayment`입니다")
@@ -146,7 +304,7 @@ 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자 이상이어야 합니다")
+	orderPassword: z.string().min(6, "주문 조회 비밀번호는 6자 이상이어야 합니다").max(128, "주문 조회 비밀번호는 128자까지입니다")
 });
 /** 현금영수증을 신청할 수 있는 결제수단 — 계좌이체·가상계좌 */
 const CASH_RECEIPT_METHODS = ["BANK_TRANSFER", "VIRTUAL_ACCOUNT"];
@@ -232,9 +390,11 @@ const cashReceiptField = cashReceiptRequestSchema.optional().describe("현금영
 const startPaymentRequestSchema = z.object({
 	option: paymentOptionSchema,
 	returnUrl: z.url().max(2048).describe("결제를 마치면 돌아올 스토어프론트 주소. 스토어 결제 도메인에 등록된 도메인이어야 한다"),
-	shippingAddress: shippingAddressInputSchema,
+	shippingAddress: shippingAddressInputSchema.optional().describe("배송지. 주문서의 `requiresShipping`이 true면 필수이고 없으면 400 `SHIPPING_ADDRESS_REQUIRED`다. 배송이 필요 없는 주문(파일·코드·이용권·방문 수령만)은 보내지 않아도 된다. 보내면 형식을 검사한 뒤 버린다"),
 	guest: guestInfoSchema.optional(),
-	cashReceipt: cashReceiptField
+	withdrawalAgreement: z.boolean().optional().describe("청약철회 제한 동의. 주문서의 `withdrawal.required`가 true면 true여야 하고 아니면 400 `WITHDRAWAL_AGREEMENT_REQUIRED`다. 동의 시각이 주문에 남는다"),
+	cashReceipt: cashReceiptField,
+	coupons: couponApplicationListSchema.optional().describe("적용할 쿠폰(이슈 #47). 결제 시작이 쿠폰을 예약하고 할인한 금액으로 결제 금액을 정한다 — 응답의 `amounts`가 확정 금액이다. 적용하지 못하는 쿠폰이 하나라도 있으면 400 `COUPON_NOT_APPLICABLE`(`details`에 사유)이다. 결제가 실패하거나 만료되면 예약이 풀린다. 쿠폰을 바꾸려면 새로 결제를 시작한다(재시도는 같은 쿠폰을 쓴다)")
 });
 /**
 * 같은 결제에서 다른 결제 옵션으로 다시 시도. `returnUrl`을 생략하면 결제 시작 때의 복귀 주소를 쓴다.
@@ -307,4 +467,4 @@ const paymentMessageSchema = z.object({
 	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 };
+export { startPaymentRequestSchema as A, myCouponListQuerySchema as B, paymentStartSchema as C, residentNumberLike as D, remoteAreaSchema as E, checkoutPricingSchema as F, isShippingFulfillment as G, pricingAmountsSchema as H, couponApplicationListSchema as I, pageSchema as J, orderItemStatusSchema as K, couponApplicationSchema as L, MIN_PAYMENT_AMOUNT as M, applicableCouponSchema as N, retryPaymentRequestSchema as O, checkoutPricingRequestSchema as P, couponBenefitViewSchema as R, paymentOptionSchema as S, pgProviderSchema as T, claimStatusSchema as U, myCouponSchema as V, fulfillmentTypeField as W, requiresShippingField as Y, 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, MAX_COUPONS_PER_CHECKOUT as j, shippingAddressInputSchema as k, checkoutDeliverySchema as l, easyPayProviderResponseSchema as m, PAYMENT_RESULT_VALUES as n, cashReceiptIdentityTypeOf as o, deliveryQuoteSchema as p, pageInfoSchema as q, 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, couponResultSchema as z };

package/dist/{client-DkyvDLXK.mjs → client-CUF2xGu8.mjs}

@@ -1,5 +1,5 @@
 import { a as ANALYTICS_VISITOR_HEADER, r as ANALYTICS_SESSION_HEADER } from "./analytics-CgD70OqH.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-BeZKjYJz.mjs";
+import { A as startPaymentRequestSchema, C as paymentStartSchema, F as checkoutPricingSchema, J as pageSchema, K as orderItemStatusSchema, N as applicableCouponSchema, O as retryPaymentRequestSchema, P as checkoutPricingRequestSchema, U as claimStatusSchema, V as myCouponSchema, W as fulfillmentTypeField, Y as requiresShippingField, d as createCheckoutRequestSchema, f as deliveryQuoteRequestSchema, m as easyPayProviderResponseSchema, p as deliveryQuoteSchema, u as checkoutSessionSchema, w as paymentStatusSchema, y as paymentMethodSchema } from "./checkout-wrCpR-P1.mjs";
 import { z } from "zod";
 //#region src/http.ts
 /** 표준 엔벨로프의 $.error 상세 */
@@ -246,6 +246,7 @@ const cartItemSchema = z.object({
 	quantity: z.number().int(),
 	unitPrice: z.number().int(),
 	totalPrice: z.number().int(),
+	fulfillmentType: fulfillmentTypeField(),
 	purchasable: z.boolean(),
 	unpurchasableReason: z.enum([
 		"SOLD_OUT",
@@ -258,7 +259,8 @@ const cartSchema = z.object({
 	summary: z.object({
 		productAmount: z.number().int(),
 		deliveryFee: z.number().int(),
-		totalAmount: z.number().int()
+		totalAmount: z.number().int(),
+		requiresShipping: requiresShippingField("구매 가능한 항목 중 택배 배송이 필요한 상품이 있는가. false면 배송비가 0이고 주문서가 배송지를 받지 않는다.")
 	})
 });
 const addCartItemRequestSchema = z.object({
@@ -271,38 +273,6 @@ const updateCartItemRequestSchema = z.object({
 	optionId: z.string().optional()
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 //#endregion
-//#region src/schemas/common.ts
-const pageInfoSchema = z.object({
-	page: z.number().int(),
-	size: z.number().int(),
-	totalElements: z.number().int(),
-	totalPages: z.number().int()
-});
-function pageSchema(item) {
-	return pageInfoSchema.extend({ contents: z.array(item) });
-}
-const orderItemStatusSchema = z.enum([
-	"PAYMENT_WAITING",
-	"PAID",
-	"CONFIRMED",
-	"DISPATCHED",
-	"DELIVERING",
-	"DELIVERED",
-	"PURCHASE_DECIDED",
-	"CANCELED"
-]);
-const claimStatusSchema = z.enum([
-	"REQUESTED",
-	"HELD",
-	"COLLECTING",
-	"COLLECTED",
-	"REDELIVERING",
-	"APPROVED",
-	"REJECTED",
-	"COMPLETED",
-	"WITHDRAWN"
-]);
-//#endregion
 //#region src/schemas/catalog.ts
 const categoryNodeSchema = z.lazy(() => z.object({
 	categoryId: z.string(),
@@ -318,6 +288,8 @@ const productCardSchema = z.object({
 	discountedPrice: z.number().int().nullable().describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
 	discountRate: z.number().int().nullable().describe("할인율(%). 할인이 없으면 null"),
 	freeShipping: z.boolean(),
+	fulfillmentType: fulfillmentTypeField(),
+	requiresShipping: requiresShippingField("택배 배송이 필요한 상품인가. false면 배송비가 없고 주문서가 배송지를 받지 않는다."),
 	averageRating: z.number(),
 	reviewCount: z.number().int(),
 	soldOut: z.boolean()
@@ -411,10 +383,12 @@ const createClaimRequestSchema = z.object({
 const createClaimResultSchema = z.object({
 	claimId: z.string(),
 	status: z.literal("REQUESTED"),
-	expectedRefundAmount: z.number().int().nullable().describe("예상 환불액 — 수량 비율 상품 금액 − 반품 배송비. **배송비 환불은 여기 포함되지 않고 `deliveryFeeRefundAmount`로 따로 온다**(승인 시점의 배송 묶음 상태로 확정되기 때문이다). 교환은 환불이 없어 null이다"),
+	expectedRefundAmount: z.number().int().nullable().describe("예상 환불액 — 수량 비율 상품 실결제 금액(쿠폰 할인을 뺀 금액) − 반품 배송비 − 조건부 무료배송 미달 차감 − 쿠폰 조건 미달 차감(`couponChargeAmount`) + 되돌릴 쿠폰 차감. **배송비 환불은 여기 포함되지 않고 `deliveryFeeRefundAmount`로 따로 온다**(승인 시점의 배송 묶음 상태로 확정되기 때문이다). 교환은 환불이 없어 null이다"),
 	claimDeliveryFee: z.number().int().describe("구매자가 부담하는 반품·교환 배송비. 원 단위"),
 	quantity: z.number().int().describe("접수된 수량. 요청에서 생략하면 남은 수량 전체다"),
-	deliveryFeeRefundAmount: z.number().int().describe("환불 예정 배송비. 배송 묶음이 모두 취소되거나 판매자 귀책일 때만 0보다 크다")
+	deliveryFeeRefundAmount: z.number().int().describe("환불 예정 배송비. 배송 묶음이 모두 취소되거나 판매자 귀책일 때만 0보다 크다"),
+	couponChargeAmount: z.number().int().optional().default(0).describe("쿠폰 조건 미달 차감 예상액. 이 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. 예상 환불액에 이미 반영돼 있다. 서버는 항상 싣는다"),
+	couponChargeRefundAmount: z.number().int().optional().default(0).describe("되돌릴 쿠폰 차감 예상액 — 앞선 취소·반품에서 뺀 쿠폰 조건 미달 차감 중 이번에 돌려받을 몫이다. 예상 환불액에 이미 반영돼 있다. 서버는 항상 싣는다")
 });
 /**
 * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
@@ -439,7 +413,7 @@ const myClaimSchema = z.object({
 	productName: z.string(),
 	quantity: z.number().int().describe("접수된 수량"),
 	reason: z.string(),
-	expectedRefundAmount: z.number().int().nullable().describe("예상 환불액 — 수량 비율 상품 금액 − 반품 배송비 − 조건부 무료배송 미달 차감. **배송비 환불은 포함되지 않고 `expectedDeliveryFeeRefundAmount`로 따로 온다.** 교환은 null이다"),
+	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"),
@@ -612,8 +586,38 @@ const myOrderItemSchema = z.object({
 	quantity: z.number().int().describe("주문 수량"),
 	canceledQuantity: z.number().int().describe("취소·반품으로 환불된 누적 수량. 부분 취소가 없었으면 0이다"),
 	activeQuantity: z.number().int().describe("남은 수량 (`quantity` − `canceledQuantity`). 취소·반품·교환 요청 수량의 상한이다"),
-	totalPrice: z.number().int(),
+	totalPrice: z.number().int().describe("주문상품 금액 (즉시할인 반영, 쿠폰 전)"),
+	couponDiscountAmount: z.number().int().optional().default(0).describe("이 주문상품에 배분된 쿠폰 할인. 실결제 금액은 `totalPrice − couponDiscountAmount`다. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
 	status: orderItemStatusSchema,
+	fulfillmentType: fulfillmentTypeField(),
+	withdrawalRestricted: z.boolean().optional().default(false).describe("청약철회 제한 주문상품인가(이슈 #48). 구매자가 결제 전에 동의했고 제공이 시작되면(다운로드·열람·이용 시작) 구매자 취소·반품을 받지 않는다. 서버는 항상 싣는다"),
+	fulfillment: z.object({
+		status: z.string().describe("제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다"),
+		fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
+		note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
+		codes: z.array(z.object({
+			codeId: z.string(),
+			hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
+			revealedAt: z.string().nullable().describe("처음 열람한 시각. 열람 전이면 null")
+		})).optional().default([]).describe("코드 발급 상품의 코드(가린 값). 평문은 `fulfillment/reveal`로 연다. 환불로 회수된 코드는 싣지 않는다. 서버는 항상 싣는다"),
+		download: z.object({
+			count: z.number().int().describe("지금까지 받은 횟수"),
+			limit: z.number().int().describe("받을 수 있는 횟수"),
+			expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
+			files: z.array(z.object({
+				assetId: z.string(),
+				fileName: z.string(),
+				sizeBytes: z.number().int().nullable()
+			}))
+		}).nullable().optional().default(null).describe("파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 `downloads`로 받는다. 다른 유형은 null. 서버는 항상 싣는다")
+	}).nullable().optional().default(null).describe("비실물 상품(이용권·방문 수령 등)의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. 비실물의 `DELIVERED`는 제공 완료(방문 수령은 수령 완료)로 표시한다. 서버는 항상 싣는다"),
+	pickupLocation: z.object({
+		name: z.string().describe("수령 장소 이름"),
+		zipCode: z.string(),
+		address1: z.string(),
+		address2: z.string().nullable(),
+		phone: z.string().describe("수령 장소 연락처")
+	}).nullable().optional().default(null).describe("방문 수령 장소(이슈 #48). 방문 수령 상품(`fulfillmentType` = `PICKUP`)이고 셀러가 수령지를 지정했을 때만 있다. 상품의 현재 수령지다. 서버는 항상 싣는다"),
 	claimStatus: z.string().nullable(),
 	reviewWritten: z.boolean(),
 	autoDecisionDate: z.string().nullable()
@@ -635,14 +639,24 @@ const myOrderSchema = z.object({
 	orderId: z.string(),
 	orderedAt: z.string(),
 	items: z.array(myOrderItemSchema),
+	requiresShipping: requiresShippingField("택배 배송이 필요한 주문상품이 있는가. false면 `shippingAddress`는 주문자 이름·연락처만 있고 주소는 빈 문자열이다."),
 	shippingAddress: orderShippingAddressSchema,
 	payment: z.object({
 		method: paymentMethodSchema.describe("실제 결제수단(PG가 보고한 수단, 모르면 주문서에서 고른 수단). 결제창에서 바뀔 수 있다(카드 결제창의 간편결제 탭 등)"),
 		easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("간편결제사. `method`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 주문서에서 고른 간편결제사다. 그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
-		totalAmount: z.number().int(),
+		couponDiscountAmount: z.number().int().optional().default(0).describe("상품·주문 쿠폰 할인 합계. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+		deliveryDiscountAmount: z.number().int().optional().default(0).describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+		discounts: z.array(z.object({
+			couponId: z.string(),
+			name: z.string().describe("주문 시점 쿠폰 이름"),
+			kind: z.string().describe("쿠폰 종류. 현재 값은 `ORDER`·`PRODUCT`·`DELIVERY`이고 값이 추가될 수 있어 문자열로 받는다"),
+			discountAmount: z.number().int()
+		})).optional().default([]).describe("주문이 받은 쿠폰. 쿠폰이 없으면 빈 배열. 서버는 항상 싣는다"),
+		totalAmount: z.number().int().describe("결제 금액 (쿠폰 할인 반영)"),
 		paidAt: z.string().nullable(),
 		receiptUrl: z.url().nullable()
 	}),
+	withdrawalAgreedAt: z.string().nullable().optional().default(null).describe("청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다"),
 	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 나가지 않았습니다 — 주문 화면에 테스트 결제 배지를 표시합니다")
 });
 /**
@@ -674,6 +688,33 @@ const purchaseDecisionResultSchema = z.object({
 	status: z.literal("PURCHASE_DECIDED"),
 	decidedAt: z.string()
 });
+/**
+* 코드 열람 응답 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/fulfillment/reveal`(회원)·
+* `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/fulfillment/reveal`(비회원).
+* 평문 코드는 이 응답에만 있다. 화면에 보인 뒤 저장하지 않는다(응답은 `Cache-Control: no-store`).
+* 첫 열람 시각은 청약철회 판단의 근거(제공 개시)로 남는다.
+*/
+const fulfillmentRevealSchema = z.object({
+	orderItemId: z.string(),
+	codes: z.array(z.object({
+		codeId: z.string(),
+		code: z.string().describe("코드 평문"),
+		revealedAt: z.string().describe("처음 열람한 시각")
+	}))
+});
+/**
+* 다운로드 요청 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/downloads`(회원)·
+* `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/downloads`(비회원, 연락처·비밀번호를 함께 보낸다).
+* 파일이 하나면 `assetId`를 생략할 수 있다.
+*/
+const downloadRequestSchema = z.object({ assetId: z.string().min(1).max(64).optional().describe("받을 파일. 파일이 여러 개면 필수다") });
+/** 다운로드 응답 — 수명 300초의 서명 주소. 받을 때마다 횟수가 하나 준다 */
+const downloadLinkSchema = z.object({
+	url: z.url().describe("서명 주소. 300초 뒤 만료된다 — 받아서 바로 쓰고 저장하지 않는다"),
+	expiresAt: z.string().describe("서명 주소 만료 시각"),
+	fileName: z.string(),
+	remaining: z.number().int().describe("남은 다운로드 횟수")
+});
 //#endregion
 //#region src/schemas/review.ts
 const publicReviewSchema = z.object({
@@ -857,7 +898,16 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 			*   스토어가 결제 도메인을 등록했는데 그 안이 아니다. 등록하지 않았으면 https 주소는 모두 받는다
 			* - 503 `PAYMENT_PROVIDER_UNAVAILABLE`: 고른 PG의 결제창을 준비하지 못했다(다른 옵션으로 다시 시도)
 			*/
-			startPayment: (checkoutId, body) => http.request("POST", path`/checkout/${checkoutId}/payment`, paymentStartSchema, { body: startPaymentRequestSchema.parse(body) })
+			startPayment: (checkoutId, body) => http.request("POST", path`/checkout/${checkoutId}/payment`, paymentStartSchema, { body: startPaymentRequestSchema.parse(body) }),
+			/**
+			* `POST /checkout/{checkoutId}/pricing` — 쿠폰 금액 미리보기(이슈 #47). 주문서를 바꾸지 않고 쿠폰을 예약하지 않는다.
+			* 확정은 결제 시작의 `coupons`다. 코드 입력은 구매자당 분당 10회까지다(429 `TOO_MANY_REQUESTS`).
+			*
+			* 에러: 404 `COUPON_NOT_FOUND`(없는 코드·남의 쿠폰) · 409 `COUPONS_UNAVAILABLE`(지금 쿠폰을 쓸 수 없음)
+			*/
+			pricing: (checkoutId, body) => http.request("POST", path`/checkout/${checkoutId}/pricing`, checkoutPricingSchema, { body: checkoutPricingRequestSchema.parse(body) }),
+			/** `GET /checkout/{checkoutId}/coupons` — 이 주문서에 쓸 수 있는 내 쿠폰과 예상 할인(회원 전용) */
+			applicableCoupons: (checkoutId) => http.request("GET", path`/checkout/${checkoutId}/coupons`, z.array(applicableCouponSchema))
 		},
 		payments: {
 			/**
@@ -877,8 +927,38 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 		myOrders: {
 			list: (params) => http.request("GET", "/me/orders", pageSchema(myOrderSchema), { query: params }),
 			get: (orderId) => http.request("GET", path`/me/orders/${orderId}`, myOrderSchema),
+			/**
+			* 비회원 주문 조회 — 주문번호 + 주문할 때 적은 연락처·주문 조회 비밀번호.
+			*
+			* 에러: 404 `ORDER_NOT_FOUND`(주문이 없거나 연락처·비밀번호가 다름 — 둘을 구분하지 않는다) ·
+			* 429 `TOO_MANY_REQUESTS`(주문번호마다 10분에 5번까지 확인하고, 5번째가 틀리면 30분 잠금.
+			* 주문번호마다 하루 15번, 스토어 전체 분당 한도도 있다. 남은 시간은 `ApiError.details.retryAfterSeconds`).
+			* 맞게 조회하면 주문번호의 횟수가 초기화된다. 본문 형식은 `guestInfoSchema`의 `phone`·`orderPassword`와 같다.
+			* 429는 연락처·비밀번호가 맞아도 난다 — 「잠시 후 다시 시도」로 안내한다.
+			*/
 			getGuestOrder: (orderId, body) => http.request("POST", path`/guest/orders/${orderId}`, myOrderSchema, { body }),
 			getDelivery: (orderItemId) => http.request("GET", path`/me/order-items/${orderItemId}/delivery`, deliveryTrackingSchema),
+			/**
+			* 코드 열람 (이슈 #48) — 코드 발급 상품의 평문 코드. 처음 열람한 시각이 제공 개시 증거로 남는다.
+			*
+			* 에러: 404 `ORDER_ITEM_NOT_FOUND`(없거나 남의 주문상품) · 404 `FULFILLMENT_NOT_FOUND`(제공 전·회수됨·코드 상품 아님) ·
+			* 429 `TOO_MANY_REQUESTS`
+			*/
+			revealCode: (orderItemId) => http.request("POST", path`/me/order-items/${orderItemId}/fulfillment/reveal`, fulfillmentRevealSchema),
+			/**
+			* 파일 다운로드 (이슈 #48) — 수명 300초의 서명 주소를 받는다. 받을 때마다 남은 횟수가 준다.
+			*
+			* 에러: 404 `FULFILLMENT_NOT_FOUND`(제공 전·회수됨·파일 상품 아님) · 409 `DOWNLOAD_LIMIT_REACHED`(횟수 소진) ·
+			* 409 `DOWNLOAD_EXPIRED`(기한 지남) · 400 `ASSET_REQUIRED`(파일이 여러 개인데 `assetId` 없음)
+			*/
+			createDownload: (orderItemId, body = {}) => http.request("POST", path`/me/order-items/${orderItemId}/downloads`, downloadLinkSchema, { body: downloadRequestSchema.parse(body) }),
+			/** 비회원 다운로드 — 비회원 주문 조회와 같은 연락처·주문 조회 비밀번호로 확인한다 */
+			createGuestDownload: (orderId, orderItemId, body) => http.request("POST", path`/guest/orders/${orderId}/order-items/${orderItemId}/downloads`, downloadLinkSchema, { body }),
+			/**
+			* 비회원 코드 열람 — 비회원 주문 조회와 같은 연락처·주문 조회 비밀번호로 확인하고 같은 시도 한도를 쓴다.
+			* 틀리면 구분 없이 404 `ORDER_NOT_FOUND`다.
+			*/
+			revealGuestCode: (orderId, orderItemId, body) => http.request("POST", path`/guest/orders/${orderId}/order-items/${orderItemId}/fulfillment/reveal`, fulfillmentRevealSchema, { body }),
 			decidePurchase: (orderItemId) => http.requestVoid("POST", path`/me/order-items/${orderItemId}/purchase-decision`)
 		},
 		myClaims: {
@@ -908,12 +988,16 @@ get: () => http.request("GET", "/store", storefrontStoreSchema) },
 			remove: (reviewId) => http.requestVoid("DELETE", path`/me/reviews/${reviewId}`)
 		},
 		inquiries: { listMine: (params) => http.request("GET", "/me/inquiries", pageSchema(publicInquirySchema), { query: params }) },
-		me: { customerInquiries: {
-			create: (body) => http.request("POST", "/me/customer-inquiries", customerInquirySchema, { body: createCustomerInquiryRequestSchema.parse(body) }),
-			list: (params) => http.request("GET", "/me/customer-inquiries", pageSchema(customerInquirySchema), { query: params }),
-			get: (inquiryId) => http.request("GET", path`/me/customer-inquiries/${inquiryId}`, customerInquirySchema)
-		} }
+		me: {
+			/** `GET /me/coupons` — 내 쿠폰(이슈 #47). `status`로 사용 가능·사용함·기간 지남을 거른다 */
+			coupons: (params) => http.request("GET", "/me/coupons", z.array(myCouponSchema), { query: params }),
+			customerInquiries: {
+				create: (body) => http.request("POST", "/me/customer-inquiries", customerInquirySchema, { body: createCustomerInquiryRequestSchema.parse(body) }),
+				list: (params) => http.request("GET", "/me/customer-inquiries", pageSchema(customerInquirySchema), { query: params }),
+				get: (inquiryId) => http.request("GET", path`/me/customer-inquiries/${inquiryId}`, customerInquirySchema)
+			}
+		}
 	};
 }
 //#endregion
-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 };
+export { anonymousSessionSchema as $, customerInquirySchema as A, createClaimRequestSchema as B, updateProfileRequestSchema as C, publicInquirySchema as D, createInquiryResultSchema as E, consentUpdateRequestSchema as F, productDetailSchema as G, myClaimSchema as H, memberConsentsSchema as I, productSortSchema as J, productFacetsSchema as K, claimReasonSchema as L, consentKindSchema as M, consentSourceSchema as N, createCustomerInquiryRequestSchema as O, consentStateSchema as P, updateCartItemRequestSchema as Q, claimReturnAddressSchema as R, memberSchema as S, createInquiryRequestSchema as T, categoryNodeSchema as U, createClaimResultSchema as V, productCardSchema as W, cartItemSchema as X, addCartItemRequestSchema as Y, cartSchema as Z, orderShippingAddressSchema as _, publicReviewSchema as a, loginRequestSchema as at, memberAddressRequestSchema as b, updateReviewRequestSchema as c, socialProviderSchema as ct, deliveryTrackingSchema as d, withdrawalBlockedDetailsSchema as dt, idpAgreementsSchema as et, downloadLinkSchema as f, ApiError as ft, myOrderSchema as g, myOrderItemSchema as h, unwrapData as ht, createReviewResultSchema as i, linkIdentityRequestSchema as it, consentActionSchema as j, customerInquiryCategorySchema as k, updateReviewResultSchema as l, tokenPairSchema as lt, fulfillmentRevealSchema as m, toApiError as mt, storefrontStoreSchema as n, idpAuthorizeResponseSchema as nt, reviewPageSchema as o, memberIdentitiesSchema as ot, downloadRequestSchema as p, buildQuery as pt, productPageSchema as q, createReviewRequestSchema as r, idpTokenRequestSchema as rt, reviewSummarySchema as s, signupRequestSchema as st, createStorefrontClient as t, idpAuthorizeRequestSchema as tt, writableReviewSchema as u, withdrawRequestSchema as ut, purchaseDecisionResultSchema as v, wishlistAddResultSchema as w, memberAddressSchema as x, trackingStageResponseSchema as y, claimTypeSchema as z };