@sayren/store-sdk 0.16.0 → 0.17.0

package/dist/index.mjs

@@ -975,6 +975,7 @@ const claimSchema = z.object({
 		carrierCode: z.string().nullable(),
 		trackingNumber: z.string().nullable()
 	}).nullable(),
+	fulfillmentType: z.string().optional().default("SHIPPING").describe("클레임 대상 주문상품의 상품 유형(이슈 #48). 수거가 없는 비실물(`DOWNLOAD`·`CODE`·`SERVICE`) 반품은 수거 등록 없이 접수·보류에서 바로 승인한다. 값이 추가될 수 있어 문자열로 받는다. 서버는 항상 싣는다"),
 	requestedAt: z.string(),
 	completedAt: z.string().nullable(),
 	/** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
@@ -1020,14 +1021,857 @@ const rejectClaimRequestSchema = z.object({
 });
 const approveClaimResultSchema = z.object({
 	claimId: z.string(),
-	refundAmount: z.number().int().describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − 추가 차감(`deductAmount`)"),
+	refundAmount: z.number().int().describe("실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − 쿠폰 조건 미달 차감(`couponChargeAmount`) + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)"),
 	deductAmount: z.number().int().describe("승인 때 셀러가 추가로 차감한 금액"),
 	quantity: z.number().int().describe("환불한 수량"),
 	deliveryFeeRefundAmount: z.number().int().describe("환불에 포함된 배송비. 배송 묶음 전량 취소나 판매자 귀책일 때만 0보다 크다"),
 	deliveryFeeChargeAmount: z.number().int().describe("환불액에서 뺀 **배송비** — 반품·교환 배송비 + 조건부 무료배송 미달 차감. 추가 차감(`deductAmount`)은 포함하지 않는다"),
+	couponChargeAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감. 남은 주문상품이 쿠폰 조건을 잃었을 때만 0보다 크다. 서버는 항상 싣는다"),
+	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
 	refundedAt: z.string()
 });
 //#endregion
+//#region src/schemas/refund-policy.ts
+/**
+* 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
+*
+* 두 층이다. 스토어 설정(`PATCH /v1/store`의 `refundPolicy`)이 기본값이고, 상품별 정책
+* (`POST/PUT /v1/products`의 `refundPolicy`)이 그 상품에만 덮어쓴다. 상품이 정하지 않은 항목은
+* 스토어 기본을 따르고, 스토어도 정하지 않았으면 `REFUND_POLICY_DEFAULTS`다.
+*
+* 한 주문에 정책이 섞이면 **상품별로 계산한다**. 배송비 묶음도 상품 단위다(주문서·장바구니의
+* 배송비 합산과 같은 규칙: 같은 상품의 주문상품이 한 묶음이고 묶음마다 배송비가 붙는다).
+*/
+const descriptions$3 = {
+	preShipmentDeliveryFeeRefund: "발송 전 취소로 배송 묶음(같은 상품의 주문상품)이 모두 취소되면 그 묶음의 배송비를 환불한다. false면 배송비를 환불하지 않는다. 기본 true",
+	returnDeliveryFee: "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). 상품별 정책에서 이 값을 주면 상품의 `returnFee`도 같은 값으로 맞춘다",
+	exchangeDeliveryFee: "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). 상품별 정책에서 이 값을 주면 상품의 `exchangeFee`도 같은 값으로 맞춘다",
+	sellerFaultFreeShipping: "판매자 귀책(셀러 직권취소, 불량·오배송 반품)이면 배송비를 셀러가 부담한다 — 배송비를 환불하고 반품비를 받지 않는다. false면 구매자 귀책과 같은 규칙을 쓴다. 기본 true",
+	conditionalFreeShortfallCharge: "조건부 무료배송(`CONDITIONAL_FREE`) 상품에서 일부 취소로 남은 금액이 무료 기준액에 미달하면 그 배송비를 환불액에서 뺀다. false면 추가 청구 없이 셀러가 부담한다. 기본 false",
+	couponShortfallCharge: "쿠폰 조건 미달 차감. 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. 판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true"
+};
+/** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
+const refundPolicySchema = z.object({
+	preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions$3.preShipmentDeliveryFeeRefund),
+	returnDeliveryFee: z.number().int().min(0).describe(descriptions$3.returnDeliveryFee),
+	exchangeDeliveryFee: z.number().int().min(0).describe(descriptions$3.exchangeDeliveryFee),
+	sellerFaultFreeShipping: z.boolean().describe(descriptions$3.sellerFaultFreeShipping),
+	conditionalFreeShortfallCharge: z.boolean().describe(descriptions$3.conditionalFreeShortfallCharge),
+	couponShortfallCharge: z.boolean().optional().default(true).describe(`${descriptions$3.couponShortfallCharge}. 이 필드가 없는 이전 서버 응답은 true로 읽는다`)
+});
+/**
+* 스토어가 정하지 않았을 때 서버가 쓰는 값.
+*
+* `as const`가 아니라 `RefundPolicy`로 타입을 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
+* `true` 자리에 `false`를 넣을 수 없다.
+*/
+const REFUND_POLICY_DEFAULTS = {
+	preShipmentDeliveryFeeRefund: true,
+	returnDeliveryFee: 0,
+	exchangeDeliveryFee: 0,
+	sellerFaultFreeShipping: true,
+	conditionalFreeShortfallCharge: false,
+	couponShortfallCharge: true
+};
+/**
+* 부분 정책 — 스토어 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
+*
+* `strictObject`라 모르는 키는 400이다. 오타(`returnFee` 등)를 조용히 무시하면 셀러는 저장됐다고
+* 믿는데 정책은 기본값으로 남는다.
+*/
+const refundPolicyPatchSchema = z.strictObject({
+	preShipmentDeliveryFeeRefund: z.boolean().optional().describe(descriptions$3.preShipmentDeliveryFeeRefund),
+	returnDeliveryFee: z.number().int().min(0).optional().describe(descriptions$3.returnDeliveryFee),
+	exchangeDeliveryFee: z.number().int().min(0).optional().describe(descriptions$3.exchangeDeliveryFee),
+	sellerFaultFreeShipping: z.boolean().optional().describe(descriptions$3.sellerFaultFreeShipping),
+	conditionalFreeShortfallCharge: z.boolean().optional().describe(descriptions$3.conditionalFreeShortfallCharge),
+	couponShortfallCharge: z.boolean().optional().describe(descriptions$3.couponShortfallCharge)
+});
+/**
+* 상품별 덮어쓰기 — 쿠폰 조건 미달 차감(`couponShortfallCharge`)은 주문 단위 규칙이라 상품이 정하지 않는다.
+* 스토어 정책만 읽는다(이슈 #47).
+*/
+const productRefundPolicyPatchSchema = refundPolicyPatchSchema.omit({ couponShortfallCharge: true });
+/**
+* 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
+*
+* 반품비·교환비는 레거시 필드(`products.returnFee`·`exchangeFee`)와 **연결**한다. 상품이
+* `refundPolicy.returnDeliveryFee`를 정하면 그 값이 원천이고(서버가 `returnFee`도 같은 값으로 맞춘다),
+* 정하지 않았으면 레거시 값이 0보다 클 때 그 값을 쓴다. 0이면 스토어 기본을 따른다 —
+* 정책이 생기기 전에 만든 상품(반품비 0)이 스토어 기본을 물려받게 하는 규칙이다.
+*/
+function resolveRefundPolicy(storePolicy, product) {
+	return {
+		...REFUND_POLICY_DEFAULTS,
+		...dropUndefined(storePolicy),
+		...productRefundPolicyOverride(product) ?? {}
+	};
+}
+/**
+* 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
+*
+* `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
+* 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
+* 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
+*/
+function productRefundPolicyOverride(product) {
+	const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product?.refundPolicy);
+	const legacy = {};
+	if (override.returnDeliveryFee === void 0 && (product?.returnFee ?? 0) > 0) legacy.returnDeliveryFee = product?.returnFee ?? 0;
+	if (override.exchangeDeliveryFee === void 0 && (product?.exchangeFee ?? 0) > 0) legacy.exchangeDeliveryFee = product?.exchangeFee ?? 0;
+	const merged = {
+		...legacy,
+		...override
+	};
+	if (product?.refundPolicy == null && Object.keys(merged).length === 0) return null;
+	return merged;
+}
+/** `undefined` 값을 빼고 얕게 복사한다 — 전개 순서로 덮어쓸 때 `undefined`가 기본값을 지우지 않게 */
+function dropUndefined(patch) {
+	if (!patch) return {};
+	return Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== void 0));
+}
+/**
+* 수량 단위 부분 취소의 환불 기준액 — **누적 내림의 차분**이다.
+*
+* 원 단위 반올림 규칙: `floor(주문상품 금액 × 누적 수량 ÷ 전체 수량)`을 두 번 구해 그 차를 쓴다.
+* 부분 취소를 몇 번 나눠도 합이 주문상품 금액과 정확히 같아서 1원이 남거나 넘치지 않는다.
+* 즉시할인은 이미 단가에 들어 있다. 쿠폰 할인은 단가에 들어가지 않으므로 환불은 실결제 금액을 나누는
+* `proratedPaidRefundBase`(promotion.ts)를 쓴다(이슈 #47).
+*
+* @param totalPrice 주문상품 금액 (할인 반영 단가 × 전체 수량)
+* @param quantity 주문상품 전체 수량
+* @param settledQuantity 이미 취소·반품된 누적 수량
+* @param cancelQuantity 이번에 취소·반품할 수량
+*/
+function proratedRefundBase(totalPrice, quantity, settledQuantity, cancelQuantity) {
+	if (quantity <= 0 || cancelQuantity <= 0) return 0;
+	const before = Math.floor(totalPrice * settledQuantity / quantity);
+	const after = Math.floor(totalPrice * (settledQuantity + cancelQuantity) / quantity);
+	return Math.max(0, after - before);
+}
+//#endregion
+//#region src/schemas/promotion.ts
+/**
+* 쿠폰 금액 계산 (이슈 #47) — 쿠폰 할인을 **얼마나, 어느 주문상품에** 주는지를 정한다.
+*
+* 계산은 순수 함수 `quotePricing` 하나다. 장바구니 요약, 주문서 미리보기, 결제 시작의 최종 확정,
+* 주문 스냅샷, 환불 정산의 조건 미달 판정(`settleCouponShortfall`)이 모두 이 함수를 지난다.
+* 다섯 경로가 각자 계산하면 화면 금액, 결제 금액, 환불 금액이 갈라진다(`quoteDelivery`와 같은 원칙).
+*
+* 계산 순서
+* 1. 즉시할인(`products.discount`)은 이미 단가에 들어 있다. 입력 `amount`가 즉시할인 반영 금액이다.
+* 2. 상품 쿠폰(`PRODUCT`) — 주문상품 한 줄에 한 장. 그 줄 금액을 기준으로 할인한다.
+* 3. 주문 쿠폰(`ORDER`) — 주문에 한 장. **상품 쿠폰 차감 뒤 금액**의 대상 합계를 기준으로 할인하고,
+*    대상 줄에 금액 비율로 나눈다(누적 내림의 차분).
+* 4. 배송비 쿠폰(`DELIVERY`) — 주문에 한 장. 기본 배송비(지역 추가 배송비 제외)를 기준으로 할인하고
+*    배송 묶음에 기본 배송비 비율로 나눈다.
+*
+* 무료배송 기준(상품별 조건부 무료·스토어 전체 기준)은 **쿠폰 차감 전 금액**으로 판정한다. 그래서 배송비
+* 견적(`quoteDelivery`)은 쿠폰과 무관하게 먼저 계산되고, 이 함수는 그 결과만 입력으로 받는다.
+*
+* 최소 주문 금액은 대상 상품의 **즉시할인 반영 합계**(쿠폰 차감 전, 배송비 제외)로 판정한다.
+* 정률 할인은 10원 단위로 내리고(`discountedPriceOf`의 즉시할인과 같은 단위), 최대 할인액과 기준 금액을
+* 넘지 않는다.
+*/
+const descriptions$2 = {
+	kind: "쿠폰 종류. `ORDER`=주문 쿠폰(대상 상품 합계에서 할인), `PRODUCT`=상품 쿠폰(주문상품 한 줄에서 할인), `DELIVERY`=배송비 쿠폰(기본 배송비에서 할인, 지역 추가 배송비 제외)",
+	benefitType: "할인 방식. `RATE`=정률(%), `AMOUNT`=정액(원)",
+	benefitValue: "할인 값. `RATE`면 1~100(%), `AMOUNT`면 원 단위 금액",
+	maxDiscountAmount: "정률 할인의 최대 할인액(원). null이면 상한이 없다. 정액 할인에는 쓰지 않는다(null)",
+	minOrderAmount: "최소 주문 금액(원). 대상 상품의 즉시할인 반영 합계(배송비 제외)가 이 값 이상이어야 쓸 수 있다. 0이면 조건이 없다",
+	firstOrderOnly: "이 스토어에서 결제 완료 주문이 없는 회원만 쓸 수 있다",
+	memberOnly: "회원만 쓸 수 있다. false면 비회원도 쓸 수 있다 — 코드 입력형이면서 1인 한도가 없는 쿠폰만 false로 둘 수 있다",
+	stackWithInstantDiscount: "상품 즉시할인과 함께 쓸 수 있다. false면 즉시할인이 걸린 주문상품은 쿠폰 대상에서 빠진다",
+	includeProductIds: "대상 상품 id. 포함 목록(상품·카테고리)이 모두 비면 전 상품이 대상이다",
+	includeCategoryIds: "대상 카테고리 id. 하위 카테고리의 상품도 대상이다",
+	excludeProductIds: "제외 상품 id. 포함보다 우선한다",
+	excludeCategoryIds: "제외 카테고리 id. 하위 카테고리의 상품도 제외한다. 포함보다 우선한다"
+};
+/** 쿠폰 종류 */
+const couponKindSchema = z.enum([
+	"ORDER",
+	"PRODUCT",
+	"DELIVERY"
+]).describe(descriptions$2.kind);
+/** 쿠폰 혜택 — 정률은 1~100%, 최대 할인액을 둘 수 있다. 정액은 최대 할인액이 없다 */
+const couponBenefitSchema = z.object({
+	type: z.enum(["RATE", "AMOUNT"]).describe(descriptions$2.benefitType),
+	value: z.number().int().min(1).describe(descriptions$2.benefitValue),
+	maxDiscountAmount: z.number().int().min(1).nullable().describe(descriptions$2.maxDiscountAmount)
+}).superRefine((benefit, ctx) => {
+	if (benefit.type === "RATE" && benefit.value > 100) ctx.addIssue({
+		code: "custom",
+		path: ["value"],
+		message: "정률 할인은 1~100(%)이어야 합니다"
+	});
+	if (benefit.type === "AMOUNT" && benefit.maxDiscountAmount !== null) ctx.addIssue({
+		code: "custom",
+		path: ["maxDiscountAmount"],
+		message: "정액 할인에는 최대 할인액을 두지 않습니다"
+	});
+});
+/** 쿠폰 사용 조건 */
+const couponConditionsSchema = z.object({
+	minOrderAmount: z.number().int().min(0).describe(descriptions$2.minOrderAmount),
+	firstOrderOnly: z.boolean().describe(descriptions$2.firstOrderOnly),
+	memberOnly: z.boolean().describe(descriptions$2.memberOnly),
+	stackWithInstantDiscount: z.boolean().describe(descriptions$2.stackWithInstantDiscount)
+});
+/** 조건을 생략했을 때의 값 */
+const COUPON_CONDITIONS_DEFAULTS = {
+	minOrderAmount: 0,
+	firstOrderOnly: false,
+	memberOnly: true,
+	stackWithInstantDiscount: true
+};
+/** 상한 — 대상 목록은 규칙 스냅샷에 통째로 복사되므로 크기를 제한한다 */
+const COUPON_TARGET_LIST_MAX = 500;
+/** 쿠폰 대상 — 포함 목록이 모두 비면 전 상품이다. 제외가 포함보다 우선한다 */
+const couponTargetSchema = z.object({
+	includeProductIds: z.array(z.string().min(1)).max(500).describe(descriptions$2.includeProductIds),
+	includeCategoryIds: z.array(z.string().min(1)).max(500).describe(descriptions$2.includeCategoryIds),
+	excludeProductIds: z.array(z.string().min(1)).max(500).describe(descriptions$2.excludeProductIds),
+	excludeCategoryIds: z.array(z.string().min(1)).max(500).describe(descriptions$2.excludeCategoryIds)
+});
+const COUPON_TARGET_ALL = {
+	includeProductIds: [],
+	includeCategoryIds: [],
+	excludeProductIds: [],
+	excludeCategoryIds: []
+};
+/**
+* 쿠폰 규칙 스냅샷 — 계산에 필요한 값만 담는다. 결제 시작이 쿠폰을 읽어 이 형태로 결제 세션에 굳히고,
+* 주문 생성·환불 정산은 이 스냅샷만 읽는다. 결제 도중·주문 뒤 셀러가 쿠폰을 바꿔도 그 주문의 금액은 움직이지 않는다.
+*/
+const couponRuleSchema = z.object({
+	couponId: z.string().describe("쿠폰 id (`cpn_…`)"),
+	name: z.string().describe("쿠폰 이름"),
+	kind: couponKindSchema,
+	benefit: couponBenefitSchema,
+	conditions: couponConditionsSchema,
+	target: couponTargetSchema,
+	startsAt: z.iso.datetime({ offset: true }).nullable().describe("사용 시작 시각(ISO 8601, 시간대 포함). null이면 제한이 없다"),
+	endsAt: z.iso.datetime({ offset: true }).nullable().describe("사용 종료 시각(ISO 8601, 시간대 포함, 이 시각부터 못 쓴다). null이면 제한이 없다")
+});
+/** 쿠폰을 적용하지 못한 사유 */
+const couponRejectReasonSchema = z.enum([
+	"DUPLICATE_COUPON",
+	"STACK_LIMIT",
+	"NOT_STARTED",
+	"EXPIRED",
+	"MEMBER_ONLY",
+	"FIRST_ORDER_ONLY",
+	"NO_ELIGIBLE_ITEMS",
+	"MIN_ORDER_AMOUNT",
+	"LINE_NOT_ELIGIBLE",
+	"NO_DISCOUNT"
+]).describe("쿠폰을 적용하지 못한 사유. `DUPLICATE_COUPON`=같은 쿠폰을 두 번 넣음, `STACK_LIMIT`=같은 종류의 쿠폰이 이미 적용됨(주문 쿠폰·배송비 쿠폰은 주문당 1장, 상품 쿠폰은 주문상품 한 줄에 1장), `NOT_STARTED`=사용 기간 전, `EXPIRED`=사용 기간 지남, `MEMBER_ONLY`=회원 전용, `FIRST_ORDER_ONLY`=첫 구매 전용, `NO_ELIGIBLE_ITEMS`=대상 상품이 주문에 없음, `MIN_ORDER_AMOUNT`=최소 주문 금액 미달, `LINE_NOT_ELIGIBLE`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, `NO_DISCOUNT`=할인할 금액이 없음");
+/** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
+const MIN_PAYMENT_AMOUNT = 100;
+/**
+* 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
+*
+* 곱셈을 먼저 하고 나눈다. `base × 율 ÷ 1000`을 내려 10을 곱하면 `floor(base × 율 / 100 / 10) × 10`과 같고
+* 부동소수 오차가 끼지 않는다.
+*/
+function couponDiscountOf(benefit, base) {
+	if (base <= 0) return 0;
+	let raw = benefit.type === "RATE" ? Math.floor(base * benefit.value / 1e3) * 10 : benefit.value;
+	if (benefit.type === "RATE" && benefit.maxDiscountAmount !== null) raw = Math.min(raw, benefit.maxDiscountAmount);
+	return Math.max(0, Math.min(raw, base));
+}
+/**
+* 금액을 가중치 비율로 나눈다 — **누적 내림의 차분**이다.
+*
+* `i`번째 몫 = `floor(total × W_i / W) − floor(total × W_{i−1} / W)`(`W_i`는 앞에서부터 누적 가중치).
+* 합이 `total`과 정확히 같고, 입력 순서가 같으면 결과도 같다. `total ≤ W`이면 몫이 가중치를 넘지 않는다.
+* 곱이 2^53을 넘을 수 있어 BigInt로 계산한다.
+*/
+function allocateByWeight(total, weights) {
+	if (!Number.isSafeInteger(total) || !weights.every((w) => Number.isSafeInteger(w))) throw new RangeError("allocateByWeight: 금액과 가중치는 안전한 정수여야 합니다");
+	const sum = weights.reduce((acc, w) => acc + Math.max(0, w), 0);
+	if (total <= 0 || sum <= 0) return weights.map(() => 0);
+	const bigTotal = BigInt(total);
+	const bigSum = BigInt(sum);
+	let cumulative = 0n;
+	let previous = 0n;
+	return weights.map((weight) => {
+		cumulative += BigInt(Math.max(0, weight));
+		const upTo = bigTotal * cumulative / bigSum;
+		const share = upTo - previous;
+		previous = upTo;
+		return Number(share);
+	});
+}
+/** 카테고리 경로(`/a/b/c/`)가 그 카테고리 또는 하위를 가리키는가 */
+function inCategory(categoryPath, categoryIds) {
+	if (!categoryPath || categoryIds.length === 0) return false;
+	const chain = categoryPath.split("/").filter(Boolean);
+	return categoryIds.some((id) => chain.includes(id));
+}
+/** 줄이 쿠폰 대상인가 — 제외가 포함보다 우선하고, 포함 목록이 모두 비면 전 상품이다 */
+function isCouponTargetLine(rule, line) {
+	const { target, conditions } = rule;
+	if (!conditions.stackWithInstantDiscount && line.amount < line.baseAmount) return false;
+	if (target.excludeProductIds.includes(line.productId)) return false;
+	if (inCategory(line.categoryPath, target.excludeCategoryIds)) return false;
+	if (target.includeProductIds.length === 0 && target.includeCategoryIds.length === 0) return true;
+	return target.includeProductIds.includes(line.productId) || inCategory(line.categoryPath, target.includeCategoryIds);
+}
+/** 시각 파싱 — 값이 없으면 null(제한 없음), 읽지 못하면 NaN(판정에서 거절한다) */
+function timeOf(value) {
+	if (!value) return null;
+	return Date.parse(value);
+}
+/**
+* 사용 기간 판정 — 쿠폰 기간과 발급 쿠폰 유효 기간 중 좁은 쪽. 시작은 포함, 종료는 제외.
+* 읽지 못하는 시각은 제한 없음이 아니라 거절이다(fail-closed).
+*/
+function periodRejectOf(coupon, now) {
+	const at = now.getTime();
+	const starts = [timeOf(coupon.rule.startsAt), timeOf(coupon.validFrom)].filter((t) => t !== null);
+	const ends = [timeOf(coupon.rule.endsAt), timeOf(coupon.validUntil)].filter((t) => t !== null);
+	if (starts.some((t) => Number.isNaN(t) || at < t)) return "NOT_STARTED";
+	if (ends.some((t) => Number.isNaN(t) || at >= t)) return "EXPIRED";
+	return null;
+}
+/**
+* 쿠폰 금액 계산 — **순수 함수다.** DB를 읽지 않는다. 규칙 스냅샷을 만드는 조회와 한도·보유 판정
+* (발급 쿠폰 상태, 1인 한도)은 호출부 몫이다.
+*
+* 종류별로 상품 쿠폰 → 주문 쿠폰 → 배송비 쿠폰 순으로 적용한다. 같은 종류의 자리와 같은 쿠폰 id는
+* **적용된** 쿠폰만 차지한다 — 앞선 주문 쿠폰이 최소 금액 미달이면 뒤의 주문 쿠폰이 쓰이고, 같은 쿠폰의 발급
+* 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
+*/
+function quotePricing(input) {
+	const lines = input.lines.map((line) => ({
+		line,
+		productDiscount: 0,
+		allocations: []
+	}));
+	const lineIndex = new Map(lines.map((entry, index) => [entry.line.lineId, index]));
+	const lineOf = (id) => {
+		const index = lineIndex.get(id);
+		return index === void 0 ? void 0 : lines[index];
+	};
+	const results = input.coupons.map((coupon) => ({
+		couponKey: coupon.couponKey ?? coupon.rule.couponId,
+		couponId: coupon.rule.couponId,
+		kind: coupon.rule.kind,
+		applied: false,
+		discount: 0,
+		rejectReason: null,
+		lineId: null,
+		eligibleLineIds: []
+	}));
+	const commonRejectOf = (coupon, result) => {
+		if (!input.ignoreEligibility) {
+			const period = periodRejectOf(coupon, input.now);
+			if (period) return period;
+			if (coupon.rule.conditions.memberOnly && !input.isMember) return "MEMBER_ONLY";
+			if (coupon.rule.conditions.firstOrderOnly && !input.firstOrder) return "FIRST_ORDER_ONLY";
+		}
+		const pinned = coupon.eligibleLineIds ? new Set(coupon.eligibleLineIds) : null;
+		const eligible = lines.filter((entry) => pinned ? pinned.has(entry.line.lineId) : isCouponTargetLine(coupon.rule, entry.line));
+		result.eligibleLineIds = eligible.map((entry) => entry.line.lineId);
+		if (eligible.length === 0) return "NO_ELIGIBLE_ITEMS";
+		if (eligible.reduce((sum, entry) => sum + entry.line.amount, 0) < coupon.rule.conditions.minOrderAmount) return "MIN_ORDER_AMOUNT";
+		return null;
+	};
+	const passed = [];
+	input.coupons.forEach((coupon, index) => {
+		const result = results[index];
+		const reason = commonRejectOf(coupon, result);
+		if (reason) result.rejectReason = reason;
+		else passed.push(index);
+	});
+	/** 적용된 쿠폰 id — 같은 쿠폰 정의는 주문에 한 장 */
+	const appliedCouponIds = /* @__PURE__ */ new Set();
+	const apply = (index, discount, lineId) => {
+		const result = results[index];
+		result.applied = true;
+		result.discount = discount;
+		result.lineId = lineId;
+		appliedCouponIds.add(result.couponId);
+	};
+	const duplicate = (index) => {
+		const result = results[index];
+		if (!appliedCouponIds.has(result.couponId)) return false;
+		result.rejectReason = "DUPLICATE_COUPON";
+		return true;
+	};
+	const productIndexes = passed.filter((index) => input.coupons[index]?.rule.kind === "PRODUCT");
+	const productOrder = [...productIndexes.filter((index) => input.coupons[index]?.lineId), ...productIndexes.filter((index) => !input.coupons[index]?.lineId).map((index) => ({
+		index,
+		width: results[index]?.eligibleLineIds.length ?? 0
+	})).sort((a, b) => a.width - b.width || a.index - b.index).map((entry) => entry.index)];
+	const takenLines = /* @__PURE__ */ new Set();
+	for (const index of productOrder) {
+		const coupon = input.coupons[index];
+		const result = results[index];
+		if (duplicate(index)) continue;
+		const candidates = result.eligibleLineIds.filter((id) => !takenLines.has(id));
+		let chosen = null;
+		let best = 0;
+		if (coupon.lineId) {
+			if (!candidates.includes(coupon.lineId)) {
+				result.rejectReason = result.eligibleLineIds.includes(coupon.lineId) ? "STACK_LIMIT" : "LINE_NOT_ELIGIBLE";
+				continue;
+			}
+			chosen = coupon.lineId;
+			best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0);
+		} else {
+			if (candidates.length === 0) {
+				result.rejectReason = "STACK_LIMIT";
+				continue;
+			}
+			for (const id of candidates) {
+				const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0);
+				if (chosen === null || discount > best) {
+					chosen = id;
+					best = discount;
+				}
+			}
+		}
+		const entry = chosen === null ? void 0 : lineOf(chosen);
+		if (!entry || chosen === null || best <= 0) {
+			result.rejectReason = "NO_DISCOUNT";
+			continue;
+		}
+		takenLines.add(chosen);
+		entry.productDiscount += best;
+		entry.allocations.push({
+			couponKey: result.couponKey,
+			amount: best
+		});
+		apply(index, best, chosen);
+	}
+	let orderSlot = false;
+	for (const index of passed) {
+		const coupon = input.coupons[index];
+		const result = results[index];
+		if (coupon.rule.kind !== "ORDER") continue;
+		if (duplicate(index)) continue;
+		if (orderSlot) {
+			result.rejectReason = "STACK_LIMIT";
+			continue;
+		}
+		const targets = result.eligibleLineIds.map((id) => lineOf(id)).filter((entry) => entry !== void 0);
+		const weights = targets.map((entry) => Math.max(0, entry.line.amount - entry.productDiscount));
+		const base = weights.reduce((sum, w) => sum + w, 0);
+		const discount = couponDiscountOf(coupon.rule.benefit, base);
+		if (discount <= 0) {
+			result.rejectReason = "NO_DISCOUNT";
+			continue;
+		}
+		const shares = allocateByWeight(discount, weights);
+		targets.forEach((entry, i) => {
+			const share = shares[i] ?? 0;
+			if (share > 0) entry.allocations.push({
+				couponKey: result.couponKey,
+				amount: share
+			});
+		});
+		orderSlot = true;
+		apply(index, discount, null);
+	}
+	const deliveryBundles = input.delivery?.bundles ?? [];
+	const bundles = deliveryBundles.map((bundle) => ({
+		bundleKey: bundle.bundleKey,
+		couponDiscount: 0
+	}));
+	let deliverySlot = false;
+	let deliveryDiscountAmount = 0;
+	for (const index of passed) {
+		const coupon = input.coupons[index];
+		const result = results[index];
+		if (coupon.rule.kind !== "DELIVERY") continue;
+		if (duplicate(index)) continue;
+		if (deliverySlot) {
+			result.rejectReason = "STACK_LIMIT";
+			continue;
+		}
+		const weights = deliveryBundles.map((bundle) => Math.max(0, bundle.fee));
+		const base = weights.reduce((sum, w) => sum + w, 0);
+		const discount = couponDiscountOf(coupon.rule.benefit, base);
+		if (discount <= 0) {
+			result.rejectReason = "NO_DISCOUNT";
+			continue;
+		}
+		allocateByWeight(discount, weights).forEach((share, i) => {
+			const bundle = bundles[i];
+			if (bundle) bundle.couponDiscount += share;
+		});
+		deliverySlot = true;
+		deliveryDiscountAmount = discount;
+		apply(index, discount, null);
+	}
+	const lineResults = lines.map((entry) => ({
+		lineId: entry.line.lineId,
+		amount: entry.line.amount,
+		couponDiscount: entry.allocations.reduce((sum, a) => sum + a.amount, 0),
+		allocations: entry.allocations
+	}));
+	const productAmount = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
+	const couponDiscountAmount = lineResults.reduce((sum, line) => sum + line.couponDiscount, 0);
+	const deliveryFee = deliveryBundles.reduce((sum, bundle) => sum + bundle.fee + bundle.remoteSurcharge, 0);
+	return {
+		lines: lineResults,
+		coupons: results,
+		bundles,
+		productAmount,
+		couponDiscountAmount,
+		deliveryFee,
+		deliveryDiscountAmount,
+		totalAmount: productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount
+	};
+}
+const NO_COUPON_SETTLEMENT = {
+	chargeAmount: 0,
+	refundAmount: 0,
+	entries: []
+};
+/**
+* 쿠폰 조건 미달 차감 — **순수 함수다.** 부분 취소·반품으로 남은 주문상품이 쿠폰 조건을 잃으면,
+* 남은 주문상품이 받던 할인만큼을 이번 환불에서 뺀다.
+*
+* 쿠폰마다
+* - `allocatedRemaining` = 남은 수량에 배분된 할인(`proratedRefundBase`로 수량 비율)
+* - `recomputed` = 주문 시점 규칙 스냅샷과 주문 시점 대상 줄로, 남은 금액만 넣어 `quotePricing`을 다시 돌린 할인
+* - 쿠폰이 **여전히 적용되면 목표 0**, 조건을 잃었으면 목표 = `allocatedRemaining`이다. 적용되는 쿠폰의
+*   정률 10원 내림 차이까지 차감하면 조건을 지킨 구매자가 몇 원씩 잃는다 — 조건을 잃은 경우만 본다.
+*   재계산 할인이 더 커지는 경우(정률 최대 할인액)도 차감하지 않고 더 돌려주지도 않는다.
+* - `delta` = 목표 − (이미 차감 + 이미 면제). 양수면 청구하고(판매자 귀책·정책 꺼짐이면 면제로 기록),
+*   음수면 앞서 뺀 차감부터 돌려준다. 마지막 활성 수량까지 취소되면 목표가 0이라 누적 차감이 모두 되돌아가고,
+*   전량 취소의 환불 합계가 결제액과 같아진다.
+* - 청구는 이번 환불에서 실제로 뺄 수 있는 금액(`chargeableAmount` + 이번에 되돌린 금액)을 넘지 않고,
+*   **실제로 뺀 금액만** 기록한다. 못 뺀 나머지는 기록하지 않아 다음 환불이 다시 본다.
+*
+* 배송비 쿠폰은 여기서 다루지 않는다. 배송비 쿠폰을 발급하게 되면(3단계) 묶음 배송비 환불
+* (`computeDeliveryFeeSettlement`)이 그 묶음의 `couponDiscount`를 빼야 한다 — 빼지 않으면 받지 않은 배송비를 돌려준다.
+*/
+function settleCouponShortfall(input) {
+	const coupons = input.coupons.filter((coupon) => coupon.rule.kind !== "DELIVERY");
+	if (coupons.length === 0) return NO_COUPON_SETTLEMENT;
+	const recomputed = quotePricing({
+		lines: input.lines.map((line) => {
+			const remaining = proratedRefundBase(line.totalPrice, line.quantity, 0, line.activeQuantity);
+			return {
+				lineId: line.lineId,
+				productId: line.productId,
+				quantity: line.activeQuantity,
+				baseAmount: remaining,
+				amount: remaining
+			};
+		}),
+		coupons: coupons.map((coupon) => ({
+			rule: coupon.rule,
+			couponKey: coupon.couponKey,
+			lineId: coupon.lineId,
+			eligibleLineIds: coupon.eligibleLineIds
+		})),
+		delivery: null,
+		firstOrder: true,
+		isMember: true,
+		now: /* @__PURE__ */ new Date(0),
+		ignoreEligibility: true
+	});
+	const base = coupons.map((coupon, index) => {
+		const allocatedRemaining = input.lines.reduce((sum, line) => {
+			return sum + proratedRefundBase(line.allocations.filter((a) => a.couponKey === coupon.couponKey).reduce((acc, a) => acc + a.amount, 0), line.quantity, 0, line.activeQuantity);
+		}, 0);
+		const result = recomputed.coupons[index];
+		const stillApplied = result?.applied === true;
+		const state = input.settlements[coupon.couponKey] ?? {};
+		return {
+			couponKey: coupon.couponKey,
+			allocatedRemaining,
+			recomputed: stillApplied ? result?.discount ?? 0 : 0,
+			target: stillApplied ? 0 : allocatedRemaining,
+			charged: Math.max(0, state.charged ?? 0),
+			waived: Math.max(0, state.waived ?? 0)
+		};
+	});
+	const entries = [];
+	let refundAmount = 0;
+	for (const item of base) {
+		const delta = item.target - (item.charged + item.waived);
+		let refund = 0;
+		let waived = item.waived;
+		if (delta < 0) {
+			refund = Math.min(item.charged, -delta);
+			waived = Math.max(0, waived - (-delta - refund));
+		}
+		refundAmount += refund;
+		entries.push({
+			couponKey: item.couponKey,
+			allocatedRemaining: item.allocatedRemaining,
+			recomputed: item.recomputed,
+			target: item.target,
+			charge: 0,
+			refund,
+			waive: 0,
+			next: {
+				charged: item.charged - refund,
+				waived
+			}
+		});
+	}
+	let capacity = Math.max(0, input.chargeableAmount) + refundAmount;
+	let chargeAmount = 0;
+	const chargeAllowed = input.shortfallCharge && !input.sellerFault;
+	for (const entry of entries) {
+		const delta = entry.target - (entry.next.charged + entry.next.waived);
+		if (delta <= 0) continue;
+		if (!chargeAllowed) {
+			entry.waive = delta;
+			entry.next = {
+				...entry.next,
+				waived: entry.next.waived + delta
+			};
+			continue;
+		}
+		const charge = Math.min(delta, capacity);
+		if (charge <= 0) continue;
+		capacity -= charge;
+		chargeAmount += charge;
+		entry.charge = charge;
+		entry.next = {
+			...entry.next,
+			charged: entry.next.charged + charge
+		};
+	}
+	return {
+		chargeAmount,
+		refundAmount,
+		entries
+	};
+}
+/**
+* 주문상품의 실결제 금액 중 이번 취소 수량의 몫 — **실결제 금액(`totalPrice − couponDiscountAmount`)을
+* 누적 내림의 차분으로 나눈다.**
+*
+* 상품 금액과 쿠폰 배분을 따로 나눠 빼면 합은 같지만 한 번의 몫이 −1원이 되는 경우가 있다
+* (예: 금액 3원·할인 2원·수량 5개에서 셋째 개). 음수를 0으로 자르면 합이 1원 넘친다. 실결제 금액을
+* 바로 나누면 몫이 항상 0 이상이고 전량 취소의 합이 실결제 금액과 정확히 같다.
+*/
+function proratedPaidRefundBase(item, settledQuantity, cancelQuantity) {
+	return proratedRefundBase(Math.max(0, item.totalPrice - (item.couponDiscountAmount ?? 0)), item.quantity, settledQuantity, cancelQuantity);
+}
+//#endregion
+//#region src/schemas/coupon.ts
+/**
+* 쿠폰 관리 API 계약 (이슈 #47) — `/v1/coupons/**`, 스코프 `promotion:r|rw`.
+*
+* 금액 계산 규칙은 `promotion.ts`(`quotePricing`)가 원천이고, 여기에는 셀러가 쿠폰을 만들고 나눠 주는 표면만 있다.
+* 발급·사용이 시작된 쿠폰은 혜택·조건·대상·사용 시작일을 바꿀 수 없다(409 `COUPON_LOCKED`). 이름·설명·종료일 연장·
+* 한도 상향·중지·재개·종료만 된다. 규칙을 바꾸려면 새 쿠폰을 만든다.
+*/
+/** 쿠폰 상태 — `ACTIVE`(사용 중)·`PAUSED`(중지, 재개 가능)·`ENDED`(종료, 되돌릴 수 없음) */
+const couponStatusSchema = z.enum([
+	"ACTIVE",
+	"PAUSED",
+	"ENDED"
+]).describe("쿠폰 상태. `ACTIVE`=사용 중, `PAUSED`=중지(재개 가능), `ENDED`=종료(되돌릴 수 없음)");
+/** 지금 만들 수 있는 발급 방식 — 다운로드·가입 자동 지급은 뒤 단계다 */
+const couponIssueMethodSchema = z.enum(["CODE", "MANUAL"]).describe("발급 방식. `CODE`=구매자가 주문서에 코드를 입력한다, `MANUAL`=셀러가 회원을 골라 지급한다");
+/** 코드 형식 — 영문·숫자·`-`·`_` 6~30자. 대소문자를 구분하지 않고 서버가 대문자로 저장한다 */
+const COUPON_CODE_PATTERN = /^[A-Za-z0-9_-]{6,30}$/;
+/** 코드 정규화 — 대문자, 앞뒤 공백 제거. 입력·저장·조회가 같은 함수를 쓴다 */
+function normalizeCouponCode(code) {
+	return code.trim().toUpperCase();
+}
+const limitField = (description) => z.number().int().min(1).max(1e7).nullable().optional().describe(description);
+const descriptions$1 = {
+	name: "구매자에게 보이는 쿠폰 이름. 1~60자",
+	description: "구매자에게 보이는 설명. 300자까지",
+	code: "쿠폰 코드 — 발급 방식이 `CODE`일 때 필수. 영문·숫자·`-`·`_` 6~30자, 대소문자 구분 없음(대문자로 저장). 스토어 안에서 유일하다",
+	startsAt: "사용 시작 시각(ISO 8601, 시간대 포함). 생략하면 바로 쓸 수 있다",
+	endsAt: "사용 종료 시각(ISO 8601, 시간대 포함). 이 시각부터 못 쓴다. 생략하면 제한이 없다. 이미 지급한 쿠폰의 유효 기간은 지급 때 정해지므로 뒤에 종료일을 늦춰도 늘어나지 않는다",
+	validDaysAfterIssue: "발급 후 유효 일수 — 셀러 지급(`MANUAL`) 쿠폰만. 쿠폰 종료일과 둘 중 먼저 끝나는 쪽이 적용된다",
+	totalIssueLimit: "총 발급 수 한도. 생략하면 무제한",
+	totalUseLimit: "총 사용 수 한도. 결제 중인 예약도 센다. 생략하면 무제한",
+	perMemberIssueLimit: "1인 발급 수 한도(셀러 지급). 생략하면 1인 1장",
+	perMemberUseLimit: "1인 사용 수 한도(코드 입력형). 생략하면 무제한. 비회원에게 여는 쿠폰은 둘 수 없다"
+};
+/** 조건 입력 — 생략한 항목은 기본값(`COUPON_CONDITIONS_DEFAULTS`)이다 */
+const couponConditionsInputSchema = z.strictObject({
+	minOrderAmount: z.number().int().min(0).optional(),
+	firstOrderOnly: z.boolean().optional(),
+	memberOnly: z.boolean().optional(),
+	stackWithInstantDiscount: z.boolean().optional()
+});
+/** 대상 입력 — 생략한 목록은 빈 목록이다(포함 목록이 모두 비면 전 상품) */
+const couponTargetInputSchema = z.strictObject({
+	includeProductIds: z.array(z.string().min(1)).max(500).optional(),
+	includeCategoryIds: z.array(z.string().min(1)).max(500).optional(),
+	excludeProductIds: z.array(z.string().min(1)).max(500).optional(),
+	excludeCategoryIds: z.array(z.string().min(1)).max(500).optional()
+});
+const couponTimeField = (description) => z.iso.datetime({ offset: true }).nullable().optional().describe(description);
+/** `POST /v1/coupons` */
+const createCouponRequestSchema = z.strictObject({
+	name: z.string().trim().min(1).max(60).describe(descriptions$1.name),
+	description: z.string().max(300).nullable().optional().describe(descriptions$1.description),
+	kind: couponKindSchema,
+	benefit: couponBenefitSchema,
+	conditions: couponConditionsInputSchema.optional().describe("사용 조건. 생략한 항목은 기본값(최소 금액 0, 회원 전용, 즉시할인과 중복 가능)"),
+	target: couponTargetInputSchema.optional().describe("대상 상품·카테고리. 생략하면 전 상품"),
+	issueMethod: couponIssueMethodSchema,
+	code: z.string().regex(COUPON_CODE_PATTERN).optional().describe(descriptions$1.code),
+	startsAt: couponTimeField(descriptions$1.startsAt),
+	endsAt: couponTimeField(descriptions$1.endsAt),
+	validDaysAfterIssue: z.number().int().min(1).max(3650).nullable().optional().describe(descriptions$1.validDaysAfterIssue),
+	totalIssueLimit: limitField(descriptions$1.totalIssueLimit),
+	totalUseLimit: limitField(descriptions$1.totalUseLimit),
+	perMemberIssueLimit: limitField(descriptions$1.perMemberIssueLimit),
+	perMemberUseLimit: limitField(descriptions$1.perMemberUseLimit)
+}).superRefine((body, ctx) => {
+	const issue = (path, message) => ctx.addIssue({
+		code: "custom",
+		path: [path],
+		message
+	});
+	if (body.issueMethod === "CODE" && !body.code) issue("code", "코드 입력형 쿠폰은 코드가 필요합니다");
+	if (body.issueMethod !== "CODE" && body.code) issue("code", "코드는 코드 입력형 쿠폰에만 둡니다");
+	if (body.issueMethod === "CODE" && body.validDaysAfterIssue != null) issue("validDaysAfterIssue", "발급 후 유효 일수는 셀러 지급 쿠폰에만 둡니다");
+	if (body.issueMethod === "CODE" && body.perMemberIssueLimit != null) issue("perMemberIssueLimit", "1인 발급 수 한도는 셀러 지급 쿠폰에만 둡니다");
+	if (body.issueMethod === "MANUAL" && body.perMemberUseLimit != null) issue("perMemberUseLimit", "셀러 지급 쿠폰은 발급 한 장이 한 번 쓰입니다. 1인 발급 수 한도를 쓰십시오");
+	if (!(body.conditions?.memberOnly ?? COUPON_CONDITIONS_DEFAULTS.memberOnly) && (body.issueMethod !== "CODE" || body.perMemberUseLimit != null)) issue("conditions", "비회원에게 여는 쿠폰은 코드 입력형이면서 1인 사용 한도가 없어야 합니다");
+	if (body.startsAt && body.endsAt && Date.parse(body.endsAt) <= Date.parse(body.startsAt)) issue("endsAt", "종료 시각은 시작 시각보다 뒤여야 합니다");
+});
+/**
+* `PATCH /v1/coupons/{couponId}` — 준 항목만 바뀐다. 발급·사용이 시작된 쿠폰(`locked`)은 이름·설명·종료일 연장·
+* 한도 상향만 받고, 그 밖의 항목이 현재 값과 다르면 409 `COUPON_LOCKED`다. 종류·발급 방식은 바꿀 수 없다.
+*/
+const updateCouponRequestSchema = z.strictObject({
+	name: z.string().trim().min(1).max(60).optional().describe(descriptions$1.name),
+	description: z.string().max(300).nullable().optional().describe(descriptions$1.description),
+	benefit: couponBenefitSchema.optional(),
+	conditions: couponConditionsInputSchema.optional(),
+	target: couponTargetInputSchema.optional(),
+	code: z.string().regex(COUPON_CODE_PATTERN).optional().describe(descriptions$1.code),
+	startsAt: couponTimeField(descriptions$1.startsAt),
+	endsAt: couponTimeField(descriptions$1.endsAt),
+	validDaysAfterIssue: z.number().int().min(1).max(3650).nullable().optional(),
+	totalIssueLimit: limitField(descriptions$1.totalIssueLimit),
+	totalUseLimit: limitField(descriptions$1.totalUseLimit),
+	perMemberIssueLimit: limitField(descriptions$1.perMemberIssueLimit),
+	perMemberUseLimit: limitField(descriptions$1.perMemberUseLimit)
+});
+/** 쿠폰 응답 */
+const couponSchema = z.object({
+	couponId: z.string(),
+	name: z.string(),
+	description: z.string().nullable(),
+	kind: couponKindSchema,
+	benefit: couponBenefitSchema,
+	conditions: couponConditionsSchema,
+	target: couponTargetSchema,
+	issueMethod: z.string().describe("발급 방식. 현재 값은 `CODE`·`MANUAL`이고 값이 추가될 수 있어 문자열로 받는다(다운로드·가입 자동 지급 예정)"),
+	code: z.string().nullable().describe("쿠폰 코드(대문자). 코드 입력형이 아니면 null"),
+	startsAt: z.string().nullable(),
+	endsAt: z.string().nullable(),
+	validDaysAfterIssue: z.number().int().nullable(),
+	totalIssueLimit: z.number().int().nullable(),
+	totalUseLimit: z.number().int().nullable(),
+	perMemberIssueLimit: z.number().int().nullable(),
+	perMemberUseLimit: z.number().int().nullable(),
+	issuedCount: z.number().int().describe("발급 수 — 회수한 발급도 센다. 총 발급 한도(`totalIssueLimit`)가 이 값과 비교된다"),
+	reservedCount: z.number().int().describe("결제 중인 예약 수 — 결제가 끝나거나 만료되면 풀린다"),
+	usedCount: z.number().int().describe("사용 수 — 전량 취소로 복원되면 줄어든다"),
+	status: couponStatusSchema,
+	locked: z.boolean().describe("발급·사용이 시작돼 혜택·조건·대상·사용 시작일을 바꿀 수 없는가"),
+	lockedAt: z.string().nullable(),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+/** `GET /v1/coupons` 쿼리 */
+const couponListQuerySchema = z.object({
+	status: couponStatusSchema.optional(),
+	kind: couponKindSchema.optional(),
+	issueMethod: couponIssueMethodSchema.optional(),
+	q: z.string().optional().describe("이름·코드 검색(포함)"),
+	...pageQueryShape()
+});
+/** 발급 쿠폰 상태 — 만료는 저장 상태가 아니라 조회 시각으로 판정한 값이다 */
+const couponIssueStatusSchema = z.string().describe("발급 쿠폰 상태. 현재 값은 `AVAILABLE`(사용 가능)·`RESERVED`(결제 중)·`USED`(사용함)·`REVOKED`(회수)·`EXPIRED`(유효 기간 지남)이고 값이 추가될 수 있어 문자열로 받는다");
+const couponIssueSchema = z.object({
+	issueId: z.string(),
+	couponId: z.string(),
+	customerId: z.string(),
+	customerName: z.string().nullable().describe("구매자 이름. 탈퇴한 구매자는 null"),
+	status: couponIssueStatusSchema,
+	validFrom: z.string(),
+	validUntil: z.string().nullable(),
+	usedOrderId: z.string().nullable(),
+	issuedAt: z.string(),
+	revokedAt: z.string().nullable()
+});
+const couponIssueListQuerySchema = z.object({
+	status: z.enum([
+		"AVAILABLE",
+		"RESERVED",
+		"USED",
+		"REVOKED"
+	]).optional(),
+	...pageQueryShape()
+});
+/** `POST /v1/coupons/{couponId}/issues` — 셀러 지급. 한 번에 1,000명까지 */
+const issueCouponRequestSchema = z.strictObject({ customerIds: z.array(z.string().min(1)).min(1).max(1e3).refine((ids) => new Set(ids).size === ids.length, "같은 구매자를 두 번 넣었습니다").describe("지급할 구매자 id(1~1,000명, 중복 불가)") });
+const issueCouponResultSchema = z.object({
+	issued: z.array(z.object({
+		customerId: z.string(),
+		issueId: z.string()
+	})),
+	failed: z.array(z.object({
+		customerId: z.string(),
+		code: z.string().describe("실패 사유. `CUSTOMER_NOT_FOUND`(이 스토어 구매자가 아님)·`COUPON_LIMIT_REACHED`(1인 발급 한도)·`COUPON_EXHAUSTED`(총 발급 한도)"),
+		message: z.string()
+	}))
+});
+const couponRedemptionSchema = z.object({
+	redemptionId: z.string(),
+	couponId: z.string(),
+	issueId: z.string().nullable(),
+	customerId: z.string().nullable().describe("구매자 id. 비회원 주문은 null"),
+	orderId: z.string().nullable().describe("주문 id. 결제가 끝나기 전의 예약·해제는 null"),
+	status: z.string().describe("사용 기록 상태. 현재 값은 `RESERVED`(결제 중)·`USED`(사용함)·`RELEASED`(결제 실패·만료로 해제)·`RESTORED`(전량 취소로 복원)이고 값이 추가될 수 있어 문자열로 받는다"),
+	discountAmount: z.number().int(),
+	reservedAt: z.string(),
+	usedAt: z.string().nullable(),
+	releasedAt: z.string().nullable(),
+	restoredAt: z.string().nullable(),
+	restoreSkippedReason: z.string().nullable().describe("전량 취소에도 복원하지 않은 사유 — `EXPIRED`(유효 기간 지남)·`ENDED`(종료된 쿠폰)")
+});
+const couponRedemptionListQuerySchema = z.object({
+	status: z.enum([
+		"RESERVED",
+		"USED",
+		"RELEASED",
+		"RESTORED"
+	]).optional(),
+	...pageQueryShape()
+});
+const couponStatsSchema = z.object({
+	couponId: z.string(),
+	issuedCount: z.number().int(),
+	revokedCount: z.number().int(),
+	reservedCount: z.number().int(),
+	usedCount: z.number().int(),
+	restoredCount: z.number().int(),
+	releasedCount: z.number().int(),
+	discountTotal: z.number().int().describe("사용 중(`USED`)인 기록의 할인 합계 (원)"),
+	orderPaymentTotal: z.number().int().describe("이 쿠폰을 쓴(`USED`) 주문의 결제 금액 합계 (원). 부분 취소·반품 환불은 빼지 않은 결제 시점 금액이다")
+});
+/** `GET /v1/customers/{customerId}/coupons` 항목 — 발급 쿠폰 + 쿠폰 이름·혜택 */
+const customerCouponSchema = couponIssueSchema.extend({
+	couponName: z.string(),
+	kind: couponKindSchema,
+	benefit: couponBenefitSchema
+});
+//#endregion
 //#region src/schemas/customer.ts
 /** 구매자 목록 정렬 */
 const customerSortSchema = z.enum([
@@ -1194,6 +2038,140 @@ const customerWithdrawalBlockedDetailsSchema = z.object({
 	pendingPayments: z.number().int()
 });
 //#endregion
+//#region src/schemas/digital-asset.ts
+/**
+* 파일 다운로드 상품의 판매 파일 (이슈 #48 단계 3).
+*
+* 파일은 CDN **비공개 객체**다. `POST /v1/uploads`(`purpose: "digital-asset"`)로 자리를 받아 응답의 `headers`와 함께 PUT하고,
+* 응답의 `key`로 상품에 연결한다. 객체 키와 파일 주소는 어떤 응답에도 싣지 않는다 — 구매자는 제공된 주문상품에서
+* 수명 300초의 서명 주소로만 받는다. 주문은 주문 시점 파일을 스냅샷하므로 파일을 바꿔도 이미 산 구매자는 옛 파일을 받는다.
+*/
+const digitalAssetAttachRequestSchema = z.object({
+	key: z.string().min(1).max(512).describe("업로드 자리 발급 응답의 `key`. 이 스토어의 비공개 업로드 키여야 한다"),
+	fileName: z.string().trim().min(1).max(200).describe("구매자에게 보일 파일 이름(확장자 포함)"),
+	sizeBytes: z.number().int().positive().optional().describe("파일 크기(바이트). 안내용이다"),
+	contentType: z.string().max(200).optional().describe("파일 형식(MIME). 안내용이다"),
+	variantId: z.string().optional().describe("이 파일을 줄 옵션(variant). 생략하면 모든 옵션의 구매자가 받는다")
+});
+/** 판매 파일 — 객체 키·주소는 싣지 않는다 */
+const digitalAssetSchema = z.object({
+	assetId: z.string(),
+	productId: z.string(),
+	variantId: z.string().nullable().describe("옵션 전용 파일이면 그 옵션, 모든 옵션 공통이면 null"),
+	fileName: z.string(),
+	contentType: z.string().nullable(),
+	sizeBytes: z.number().int().nullable(),
+	status: z.string().describe("`ACTIVE`(새 주문에 제공)·`REMOVED`(해제 — 이미 산 구매자는 계속 받는다). 값이 추가될 수 있어 문자열로 받는다"),
+	createdAt: z.string()
+});
+/** 셀러 확인용 서명 주소 — `POST /v1/products/{productId}/digital-assets/{assetId}/preview-url` */
+const digitalAssetPreviewSchema = z.object({
+	url: z.url().describe("수명 300초의 서명 주소"),
+	expiresAt: z.string()
+});
+/** 주문상품의 다운로드 제공 정보 — 주문 응답의 `fulfillment.download` */
+const orderItemDownloadSchema = z.object({
+	count: z.number().int().describe("지금까지 받은 횟수"),
+	limit: z.number().int().describe("받을 수 있는 횟수"),
+	expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
+	firstDownloadedAt: z.string().nullable().describe("처음 받은 시각 — 제공 개시 증거다"),
+	files: z.array(z.object({
+		assetId: z.string(),
+		fileName: z.string(),
+		sizeBytes: z.number().int().nullable()
+	}))
+});
+//#endregion
+//#region src/schemas/fulfillment-code.ts
+/**
+* 코드 발급 상품의 코드 풀 (이슈 #48 단계 2) — 라이선스 키·기프트 코드처럼 결제 확정과 함께 한 개씩 배정하는 코드다.
+*
+* **평문 코드는 두 경로로만 나간다** — 구매자 열람(`POST /storefront/v1/me/order-items/{id}/fulfillment/reveal`)과 셀러 콘솔
+* 열람(`POST /v1/fulfillment-codes/{codeId}/reveal`, 콘솔 전용). 목록·주문·웹훅·API 로그에는 가린 값(`hint`)만 싣는다.
+* 코드는 결제 자격 증명과 같은 키링·AES-256-GCM으로 암호화해 저장한다.
+*/
+/**
+* 코드 상태.
+* - `AVAILABLE` 판매 가능 — 재고로 센다
+* - `ASSIGNED` 주문상품에 배정됨
+* - `REVOKED` 환불로 회수됨(구매자 화면에서 숨긴다. 코드 자체의 무효화는 셀러 시스템 몫이다)
+* - `EXPIRED` 유효기간이 지나 배정하지 않음
+* - `VOID` 셀러가 폐기함
+*/
+const fulfillmentCodeStatusSchema = z.enum([
+	"AVAILABLE",
+	"ASSIGNED",
+	"REVOKED",
+	"EXPIRED",
+	"VOID"
+]);
+/** 한 번에 올릴 수 있는 코드 수 */
+const MAX_CODES_PER_UPLOAD = 1e4;
+/** 코드 한 개의 최대 길이 */
+const MAX_CODE_LENGTH = 200;
+/**
+* 코드 일괄 업로드 요청 — `POST /v1/products/{productId}/codes`. `codes`(배열)와 `csv`(본문) 중 하나를 보낸다.
+* 앞뒤 공백은 지우고 빈 줄은 건너뛴다. 같은 상품에 이미 있는 코드와 요청 안의 중복은 받지 않는다(`duplicates`).
+*/
+const fulfillmentCodeUploadRequestSchema = z.object({
+	variantId: z.string().optional().describe("코드를 채울 옵션(variant) ID. 옵션 없는 상품은 생략한다(기본 옵션)"),
+	codes: z.array(z.string()).max(MAX_CODES_PER_UPLOAD).optional().describe(`코드 목록. 한 번에 ${MAX_CODES_PER_UPLOAD}개까지. \`csv\`와 둘 중 하나만 보낸다`),
+	csv: z.string().max(4e6).optional().describe(`CSV 본문 — 줄마다 첫 칸이 코드다. 첫 줄의 첫 칸이 \`code\`면 머리글로 보고 건너뛴다. 한 번에 ${MAX_CODES_PER_UPLOAD}줄까지`),
+	expiresAt: z.iso.datetime({ offset: true }).optional().describe("이 업로드 코드의 유효기간 (ISO 8601). 지나면 배정하지 않고 만료로 바꾼다")
+}).refine((value) => value.codes === void 0 !== (value.csv === void 0), { message: "codes와 csv 중 하나만 보내야 합니다" });
+/** 받지 않은 줄 */
+const fulfillmentCodeRejectionSchema = z.object({
+	line: z.number().int().describe("요청 안의 위치 (1부터). CSV는 머리글을 포함한 줄 번호다"),
+	reason: z.string().describe("사유. `DUPLICATE`(이미 있는 코드이거나 요청 안에서 겹침)·`TOO_LONG`(200자 초과)·`INVALID_CHARACTER`(제어 문자). 값이 추가될 수 있어 문자열로 받는다")
+});
+/** 업로드 결과 — 배치 요약 */
+const fulfillmentCodeBatchSchema = z.object({
+	batchId: z.string(),
+	productId: z.string(),
+	variantId: z.string(),
+	total: z.number().int().describe("요청에서 읽은 코드 수(빈 줄·머리글 제외)"),
+	accepted: z.number().int().describe("받은 코드 수 — 재고가 이만큼 는다"),
+	duplicates: z.number().int().describe("중복이라 받지 않은 코드 수"),
+	rejected: z.array(fulfillmentCodeRejectionSchema).describe("받지 않은 줄(중복 포함). 최대 1,000개까지 싣는다"),
+	expiresAt: z.string().nullable(),
+	createdAt: z.string()
+});
+/** 코드 목록의 한 줄 — **가린 값만** 싣는다 */
+const fulfillmentCodeSchema = z.object({
+	codeId: z.string(),
+	productId: z.string(),
+	variantId: z.string(),
+	batchId: z.string().nullable().describe("업로드 배치. 수동 제공으로 셀러가 넘긴 코드는 null"),
+	hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
+	status: z.string().describe("코드 상태. `AVAILABLE`·`ASSIGNED`·`REVOKED`·`EXPIRED`·`VOID`. 값이 추가될 수 있어 문자열로 받는다"),
+	orderItemId: z.string().nullable().describe("배정된 주문상품. 배정 전이면 null"),
+	assignedAt: z.string().nullable(),
+	revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각 — 제공 개시 증거다"),
+	expiresAt: z.string().nullable(),
+	createdAt: z.string()
+});
+const fulfillmentCodePageSchema = pageSchema(fulfillmentCodeSchema).extend({ available: z.number().int().describe("판매 가능한 코드 수(필터와 무관한 상품 전체)") });
+/** `GET /v1/products/{productId}/codes` 쿼리 */
+const fulfillmentCodeListQuerySchema = z.object({
+	status: fulfillmentCodeStatusSchema.optional().describe("상태 필터"),
+	variantId: z.string().optional().describe("옵션 필터"),
+	batchId: z.string().optional().describe("업로드 배치 필터"),
+	orderItemId: z.string().optional().describe("주문상품 필터"),
+	...pageQueryShape()
+});
+/** 셀러 콘솔 코드 열람 응답 — `POST /v1/fulfillment-codes/{codeId}/reveal` */
+const fulfillmentCodeRevealSchema = z.object({
+	codeId: z.string(),
+	code: z.string().describe("코드 평문. 응답은 캐시하지 않는다(`Cache-Control: no-store`)")
+});
+/** 주문상품에 배정된 코드의 가린 값 — 주문 응답의 `fulfillment.codes` */
+const orderItemCodeSchema = z.object({
+	codeId: z.string(),
+	hint: z.string().describe("가린 코드 — 끝 4자만 보인다"),
+	status: z.string().describe("`ASSIGNED`(유효)·`REVOKED`(환불로 회수). 값이 추가될 수 있어 문자열로 받는다"),
+	revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각. 열람 전이면 null")
+});
+//#endregion
 //#region src/schemas/login.ts
 /** 소셜 로그인 공급자 */
 const loginProviderSchema = z.enum([
@@ -1358,6 +2336,7 @@ const eventTypeSchema = z.enum([
 	"ORDER.PURCHASE_DECIDED",
 	"ORDER.ADDRESS_CHANGE_REQUESTED",
 	"ORDER.CANCELED",
+	"ORDER.FULFILLED",
 	"CLAIM.CANCEL_REQUESTED",
 	"CLAIM.RETURN_REQUESTED",
 	"CLAIM.EXCHANGE_REQUESTED",
@@ -1447,7 +2426,7 @@ const webhookDeliverySchema = z.object({
 	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("마지막 시도의 실패 사유. 성공했거나 미시도면 null"),
 	failureReason: webhookFailureReasonSchema.nullable().describe("마지막 시도의 실패 원인 분류. 성공했거나 미시도면 null. `errorCode`를 더 잘게 나눈 진단 값이다"),
 	resource: webhookDeliveryResourceSchema.nullable().describe("이벤트가 가리키는 대상 리소스. 리소스를 특정할 수 없는 이벤트면 null. 이 값으로 전송 기록(`resourceId`)과 API 로그(`q`)를 오갈 수 있다"),
-	attemptCount: z.number().int().min(0).describe("지금까지의 시도 횟수. 최초 시도 1회 + 재시도 최대 4회"),
+	attemptCount: z.number().int().min(0).describe("지금까지 전송을 시작한 횟수. 최초 시도 1회 + 재시도 최대 4회. 전송 도중 장애로 결과를 기록하지 못한 시도도 센다"),
 	createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
 	attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
 	nextAttemptAt: z.string().nullable().describe("다음 시도 예정 일시 (ISO 8601). `PENDING`·`PENDING_RETRY`일 때만 값이 있다"),
@@ -1533,6 +2512,121 @@ const reviewReportResultSchema = z.object({
 	status: z.literal("PENDING_REVIEW")
 });
 //#endregion
+//#region src/schemas/fulfillment.ts
+/**
+* 상품 유형과 제공 방식 (이슈 #48) — 배송이 필요 없는 상품을 팔기 위한 축이다.
+*
+* **상품 유형은 제공 방식 하나로 표현한다.** `fulfillmentType` 한 필드가 배송 필요 여부, 이행 흐름, 재고 의미를 정한다.
+* 코드 곳곳에서 유형 이름으로 분기하지 않고 이 파일의 판정 함수(`requiresShipping`·`fulfillmentRuleOf`)를 지난다.
+* 유형이 늘어나도 판정표 한 곳만 고치면 배송비 계산·결제 시작·클레임·콘솔 버튼이 같이 따라온다.
+*
+* 주문상품 상태 enum은 바꾸지 않는다. 비실물의 **제공 완료는 `DELIVERED`를 재사용한다** — 새 상태를 더하면 기존 소비자의
+* 상태 분기(배송완료 뒤 구매확정 대기, 반품 가능 판정)가 새 값을 모른다. 표시는 `fulfillmentType`으로 가른다.
+*/
+/**
+* 상품 유형.
+* - `SHIPPING` 배송 상품(기본, 이 필드 이전의 상품 전부)
+* - `DOWNLOAD` 파일 다운로드
+* - `CODE` 코드 발급(라이선스 키·기프트 코드)
+* - `SERVICE` 이용권·상품권·서비스(예약 없음)
+* - `PICKUP` 방문 수령 실물
+*/
+const fulfillmentTypeSchema = z.enum([
+	"SHIPPING",
+	"DOWNLOAD",
+	"CODE",
+	"SERVICE",
+	"PICKUP"
+]);
+/** 제공 방식 — `AUTO`는 결제 확정과 함께 제공하고, `MANUAL`은 셀러가 제공 처리한다 */
+const fulfillmentModeSchema = z.enum(["AUTO", "MANUAL"]);
+/**
+* 응답 스키마용 유형 — 서버가 나중에 유형을 더해도 옛 SDK가 응답 파싱에서 깨지지 않게 문자열로 받는다.
+* 요청은 `fulfillmentTypeSchema`(닫힌 enum)로 검증한다.
+*/
+const fulfillmentTypeResponseSchema = z.string().describe("상품 유형. 현재 값은 `SHIPPING`(배송 상품)·`DOWNLOAD`(파일 다운로드)·`CODE`(코드 발급)·`SERVICE`(이용권·서비스)·`PICKUP`(방문 수령)이고 값이 추가될 수 있어 문자열로 받는다");
+/**
+* 유형별 규칙표 — **유일한 원천이다.**
+*
+* `PICKUP`은 실물이라 반품 수거와 교환을 받지만 택배 배송은 없다. `DOWNLOAD`는 결제 즉시 권한을 발급하므로 `AUTO`만,
+* `PICKUP`은 셀러가 수령 완료를 누르므로 `MANUAL`만 둔다.
+*/
+const FULFILLMENT_RULES = {
+	SHIPPING: {
+		requiresShipping: true,
+		modes: [],
+		defaultMode: null,
+		requiresCollection: true,
+		exchangeSupported: true
+	},
+	DOWNLOAD: {
+		requiresShipping: false,
+		modes: ["AUTO"],
+		defaultMode: "AUTO",
+		requiresCollection: false,
+		exchangeSupported: false
+	},
+	CODE: {
+		requiresShipping: false,
+		modes: ["AUTO", "MANUAL"],
+		defaultMode: "AUTO",
+		requiresCollection: false,
+		exchangeSupported: false
+	},
+	SERVICE: {
+		requiresShipping: false,
+		modes: ["MANUAL", "AUTO"],
+		defaultMode: "MANUAL",
+		requiresCollection: false,
+		exchangeSupported: false
+	},
+	PICKUP: {
+		requiresShipping: false,
+		modes: ["MANUAL"],
+		defaultMode: "MANUAL",
+		requiresCollection: true,
+		exchangeSupported: true
+	}
+};
+/**
+* 저장된 값 → 유형. null·모르는 값은 `SHIPPING`이다 — 이 필드 이전의 주문상품(`order_items.fulfillment_type` null)과
+* 상품은 모두 배송 상품이었다.
+*/
+function fulfillmentTypeOf(value) {
+	const parsed = fulfillmentTypeSchema.safeParse(value);
+	return parsed.success ? parsed.data : "SHIPPING";
+}
+/** 유형의 규칙 — 모르는 값은 배송 상품 규칙이다 */
+function fulfillmentRuleOf(type) {
+	return FULFILLMENT_RULES[fulfillmentTypeOf(type)];
+}
+/** 택배 배송이 필요한가 — 배송비 묶음·배송지·발송 흐름의 판정은 이 함수 하나를 지난다 */
+function requiresShipping(type) {
+	return fulfillmentRuleOf(type).requiresShipping;
+}
+/** 반품에 수거가 필요한가 — 비실물 반품은 수거 등록·수거 완료 없이 승인한다 */
+function requiresCollection(type) {
+	return fulfillmentRuleOf(type).requiresCollection;
+}
+/**
+* 유효 제공 방식 — 요청 값이 유형에 허용되면 그 값, 생략이면 유형 기본값이다. 배송 상품은 null이다.
+* 허용되지 않는 값은 `null`을 돌려주지 않고 호출부가 거부하도록 `undefined`를 돌려준다.
+*/
+function resolveFulfillmentMode(type, mode) {
+	const rule = FULFILLMENT_RULES[type];
+	if (rule.modes.length === 0) return null;
+	if (mode === null || mode === void 0) return rule.defaultMode;
+	return rule.modes.includes(mode) ? mode : void 0;
+}
+/**
+* 배송이 없는 주문상품의 배송 묶음 키 (`order_items.delivery_bundle_key`).
+*
+* null로 두면 환불 정산이 #29 이전 주문의 레거시 폴백(「묶음 = 같은 상품」, 상품의 **현재** 배송비)을 탄다.
+* 이 키를 만나면 배송비 환불·차감이 0이고 `orders.delivery_fee_settlements`에 항목을 만들지 않는다.
+* 정책 지문 키(`b:…`)와 겹치지 않는다.
+*/
+const NO_SHIPPING_BUNDLE_KEY = "none";
+//#endregion
 //#region src/schemas/payment.ts
 /**
 * 스토어 결제(PG) 설정과 매출 리포트 계약.
@@ -1900,6 +2994,22 @@ const shippingAddressSchema = z.object({
 	deliveryMemo: z.string().nullish(),
 	entranceCode: z.string().nullish()
 });
+/** 비실물 주문상품의 제공 정보 (이슈 #48) */
+const orderItemFulfillmentSchema = z.object({
+	status: z.string().describe("제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다"),
+	mode: z.string().nullable().describe("제공 방식. `AUTO`·`MANUAL`"),
+	fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
+	note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
+	codes: z.array(orderItemCodeSchema).optional().default([]).describe("코드 발급 상품에 배정한 코드의 가린 값. 평문은 싣지 않는다. 코드 상품이 아니면 빈 배열. 서버는 항상 싣는다"),
+	download: orderItemDownloadSchema.nullable().optional().default(null).describe("파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 싣지 않는다. 다른 유형은 null. 서버는 항상 싣는다"),
+	mail: z.object({
+		status: z.string().describe("제공 안내 메일 상태. 현재 값은 `PENDING`(보낼 예정)·`SENDING`·`SENT`·`FAILED`·`SKIPPED`(보내지 않음: 스토어 설정 꺼짐·받을 주소 없음)이고 값이 추가될 수 있다"),
+		sentAt: z.string().nullable(),
+		errorCode: z.string().nullable().describe("실패·건너뜀 사유 코드")
+	}).nullable().optional().default(null).describe("구매자에게 보낸 제공 안내 메일(이슈 #48). 기록이 없으면 null. 서버는 항상 싣는다")
+});
+/** 제공 안내 메일 재발송 결과 */
+const fulfillmentMailResendSchema = z.object({ mailStatus: z.string().describe("재발송 뒤 메일 상태 — `SENT`·`PENDING`(곧 다시 보낸다)·`FAILED`·`SKIPPED`") });
 const orderItemSchema = z.object({
 	orderItemId: z.string(),
 	orderId: z.string(),
@@ -1914,23 +3024,35 @@ const orderItemSchema = z.object({
 	optionId: z.string().nullable(),
 	optionName: z.string().nullable(),
 	sellerCode: z.string().nullable(),
+	fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING").describe("주문 시점 상품 유형. 현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. 배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, `DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. 서버는 항상 싣는다"),
 	quantity: z.number().int().describe("주문 수량"),
 	canceledQuantity: z.number().int().describe("취소·반품으로 환불된 누적 수량. 수량 단위 부분 취소가 없었으면 0이다"),
 	activeQuantity: z.number().int().describe("살아 있는 수량 (`quantity` − `canceledQuantity`). 0이면 주문상품이 전량 취소됐다"),
 	unitPrice: z.number().int(),
 	discountAmount: z.number().int(),
-	totalPrice: z.number().int().describe("주문상품 금액 (할인 반영 단가 × 주문 수량)"),
+	totalPrice: z.number().int().describe("주문상품 금액 (즉시할인 반영 단가 × 주문 수량). 쿠폰 할인 전 금액이다"),
+	couponDiscountAmount: z.number().int().optional().default(0).describe("이 주문상품에 배분된 쿠폰 할인 — 상품 쿠폰 + 주문 쿠폰 배분. 실결제 금액은 `totalPrice − couponDiscountAmount`이고 취소·반품 환불은 실결제 금액을 수량 비율로 나눈다. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
 	hold: z.object({
 		reason: z.string(),
 		expectedDispatchDate: z.string()
 	}).nullable(),
+	fulfillment: orderItemFulfillmentSchema.nullable().optional().default(null).describe("비실물 상품의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. 코드 평문·파일 주소는 싣지 않는다. 서버는 항상 싣는다"),
 	autoDecisionDate: z.string().nullable(),
 	sellerMemo: z.string().nullable(),
 	orderedAt: z.string(),
 	lastChangedAt: z.string(),
 	lastChangedType: changeTypeSchema,
+	withdrawalRestricted: z.boolean().optional().default(false).describe("청약철회 제한 주문상품인가(이슈 #48). 구매자가 결제 전에 동의했고 제공이 시작되면(다운로드·열람·이용 시작) 구매자 취소·반품을 받지 않는다. 서버는 항상 싣는다"),
 	testPayment: z.boolean().describe("소속 주문이 테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았습니다")
 });
+/** 주문이 받은 쿠폰 한 장 (이슈 #47) */
+const orderDiscountSchema = z.object({
+	couponId: z.string().describe("쿠폰 id"),
+	name: z.string().describe("주문 시점 쿠폰 이름"),
+	kind: z.string().describe("쿠폰 종류. 현재 값은 `ORDER`(주문 쿠폰)·`PRODUCT`(상품 쿠폰)·`DELIVERY`(배송비 쿠폰)이고 값이 추가될 수 있어 문자열로 받는다"),
+	discountAmount: z.number().int().describe("이 쿠폰의 할인액 (원)"),
+	issueId: z.string().nullable().describe("발급 쿠폰 id. 코드 입력형은 null")
+});
 const orderSchema = z.object({
 	orderId: z.string(),
 	orderedAt: z.string(),
@@ -1939,6 +3061,7 @@ const orderSchema = z.object({
 		phone: z.string(),
 		email: z.email().optional()
 	}),
+	requiresShipping: z.boolean().optional().default(true).describe("택배 배송이 필요한 주문상품이 있는가. false면 `shippingAddress`는 주문자 이름·연락처만 있고 주소는 빈 문자열이다. 서버는 항상 싣는다"),
 	shippingAddress: shippingAddressSchema,
 	payment: z.object({
 		method: z.enum([
@@ -1951,13 +3074,17 @@ const orderSchema = z.object({
 		]).describe("method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다"),
 		approvedMethod: z.string().nullable().optional().default(null).describe("실제 결제수단. method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다. 현재 값은 `pgPaymentMethodSchema`(`PgPaymentMethod`: CARD·BANK_TRANSFER·VIRTUAL_ACCOUNT·MOBILE·EASY_PAY)이고 매출 리포트·스토어프론트·환불 원장과 같은 값이다. 값이 추가될 수 있어 문자열로 받는다. PG가 알려 주지 않았으면 요청 수단, 시도 기록이 없는 오래된 주문은 null. 서버는 항상 싣는다"),
 		easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("승인된 간편결제사. `approvedMethod`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 요청한 간편결제사다. 그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
-		productAmount: z.number().int(),
-		deliveryFee: z.number().int(),
-		discountAmount: z.number().int(),
-		totalAmount: z.number().int(),
+		productAmount: z.number().int().describe("상품 금액 합 (즉시할인 반영, 쿠폰 전)"),
+		deliveryFee: z.number().int().describe("배송비 (쿠폰 전)"),
+		discountAmount: z.number().int().describe("즉시할인 합 (정가 − 할인 단가) × 수량. 쿠폰 할인은 `couponDiscountAmount`로 따로 온다"),
+		couponDiscountAmount: z.number().int().optional().default(0).describe("상품·주문 쿠폰 할인 합계. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+		deliveryDiscountAmount: z.number().int().optional().default(0).describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+		discounts: z.array(orderDiscountSchema).optional().default([]).describe("주문이 받은 쿠폰. 쿠폰이 없으면 빈 배열. 서버는 항상 싣는다"),
+		totalAmount: z.number().int().describe("결제 금액 = productAmount + deliveryFee − couponDiscountAmount − deliveryDiscountAmount. 쿠폰이 없는 주문은 productAmount + deliveryFee다"),
 		paidAt: z.string().nullable(),
 		cashReceipt: cashReceiptSchema.nullable().optional().default(null).describe("현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다")
 	}),
+	withdrawalAgreedAt: z.string().nullable().optional().default(null).describe("청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다"),
 	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았습니다. 상품을 발송하지 않도록 주의하십시오"),
 	items: z.array(orderItemSchema)
 });
@@ -1977,6 +3104,7 @@ const orderListQuerySchema = z.object({
 	orderedTo: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
 	status: orderItemStatusSchema.optional().describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
 	keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+	fulfillmentType: z.string().optional().describe("상품 유형 필터(이슈 #48) — 이 유형(`SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`)의 주문상품이 하나라도 있는 주문"),
 	testPayment: testPaymentQuery,
 	...pageQuery,
 	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
@@ -2078,14 +3206,29 @@ const cancelBySellerRequestSchema = z.object({
 	detail: z.string().max(500).optional(),
 	quantity: z.number().int().min(1).optional().describe("취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. 일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다")
 });
+/**
+* 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 수동 제공 비실물 주문상품(이용권·방문 수령 등)을
+* 제공 완료(`DELIVERED`)로 바꾼다.
+*/
+const fulfillRequestSchema = z.object({
+	note: z.string().trim().max(1e3).optional().describe("구매자에게 보일 이용 안내(예: 예약 방법, 수령 장소). 주문 상세에 실린다"),
+	codes: z.array(z.string().trim().min(1).max(200)).min(1).max(100).optional().describe("수동 제공 코드 발급 상품의 코드 — 셀러 시스템이 발급한 코드를 넘긴다. 남은 수량만큼 보낸다(`CODE_COUNT_MISMATCH`). 암호화해 저장하고 구매자가 열람할 때만 평문으로 나간다. 다른 유형은 보내지 않는다")
+});
+/** 제공 처리 일괄 요청 — `POST /v1/order-items/fulfill` */
+const fulfillBulkRequestSchema = z.object({
+	orderItemIds: z.array(z.string()).min(1).max(100),
+	note: fulfillRequestSchema.shape.note
+});
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 const cancelBySellerResultSchema = z.object({
 	orderItemId: z.string(),
-	refundAmount: z.number().int().describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감"),
+	refundAmount: z.number().int().describe("실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`)"),
 	quantity: z.number().int().describe("취소한 수량"),
 	canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
 	deliveryFeeRefundAmount: z.number().int().describe("환불에 포함된 배송비. 배송 묶음(같은 상품)이 모두 취소됐고 환불 정책이 켜져 있을 때만 0보다 크다"),
 	deliveryFeeChargeAmount: z.number().int().describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
+	couponChargeAmount: z.number().int().optional().default(0).describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
 	refundedAt: z.string()
 });
 /** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
@@ -2110,124 +3253,20 @@ const purchaseDecisionExtendResultSchema = z.object({
 */
 const addressChangeRequestListSchema = z.array(z.record(z.string(), z.unknown())).describe("배송지 변경 요청 목록 (현재 항상 빈 배열)");
 //#endregion
-//#region src/schemas/refund-policy.ts
-/**
-* 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
-*
-* 두 층이다. 스토어 설정(`PATCH /v1/store`의 `refundPolicy`)이 기본값이고, 상품별 정책
-* (`POST/PUT /v1/products`의 `refundPolicy`)이 그 상품에만 덮어쓴다. 상품이 정하지 않은 항목은
-* 스토어 기본을 따르고, 스토어도 정하지 않았으면 `REFUND_POLICY_DEFAULTS`다.
-*
-* 한 주문에 정책이 섞이면 **상품별로 계산한다**. 배송비 묶음도 상품 단위다(주문서·장바구니의
-* 배송비 합산과 같은 규칙: 같은 상품의 주문상품이 한 묶음이고 묶음마다 배송비가 붙는다).
-*/
-const descriptions$1 = {
-	preShipmentDeliveryFeeRefund: "발송 전 취소로 배송 묶음(같은 상품의 주문상품)이 모두 취소되면 그 묶음의 배송비를 환불한다. false면 배송비를 환불하지 않는다. 기본 true",
-	returnDeliveryFee: "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). 상품별 정책에서 이 값을 주면 상품의 `returnFee`도 같은 값으로 맞춘다",
-	exchangeDeliveryFee: "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). 상품별 정책에서 이 값을 주면 상품의 `exchangeFee`도 같은 값으로 맞춘다",
-	sellerFaultFreeShipping: "판매자 귀책(셀러 직권취소, 불량·오배송 반품)이면 배송비를 셀러가 부담한다 — 배송비를 환불하고 반품비를 받지 않는다. false면 구매자 귀책과 같은 규칙을 쓴다. 기본 true",
-	conditionalFreeShortfallCharge: "조건부 무료배송(`CONDITIONAL_FREE`) 상품에서 일부 취소로 남은 금액이 무료 기준액에 미달하면 그 배송비를 환불액에서 뺀다. false면 추가 청구 없이 셀러가 부담한다. 기본 false"
-};
-/** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
-const refundPolicySchema = z.object({
-	preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions$1.preShipmentDeliveryFeeRefund),
-	returnDeliveryFee: z.number().int().min(0).describe(descriptions$1.returnDeliveryFee),
-	exchangeDeliveryFee: z.number().int().min(0).describe(descriptions$1.exchangeDeliveryFee),
-	sellerFaultFreeShipping: z.boolean().describe(descriptions$1.sellerFaultFreeShipping),
-	conditionalFreeShortfallCharge: z.boolean().describe(descriptions$1.conditionalFreeShortfallCharge)
-});
-/**
-* 스토어가 정하지 않았을 때 서버가 쓰는 값.
-*
-* `as const`가 아니라 `RefundPolicy`로 타입을 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
-* `true` 자리에 `false`를 넣을 수 없다.
-*/
-const REFUND_POLICY_DEFAULTS = {
-	preShipmentDeliveryFeeRefund: true,
-	returnDeliveryFee: 0,
-	exchangeDeliveryFee: 0,
-	sellerFaultFreeShipping: true,
-	conditionalFreeShortfallCharge: false
-};
-/**
-* 부분 정책 — 스토어 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
-*
-* `strictObject`라 모르는 키는 400이다. 오타(`returnFee` 등)를 조용히 무시하면 셀러는 저장됐다고
-* 믿는데 정책은 기본값으로 남는다.
-*/
-const refundPolicyPatchSchema = z.strictObject({
-	preShipmentDeliveryFeeRefund: z.boolean().optional().describe(descriptions$1.preShipmentDeliveryFeeRefund),
-	returnDeliveryFee: z.number().int().min(0).optional().describe(descriptions$1.returnDeliveryFee),
-	exchangeDeliveryFee: z.number().int().min(0).optional().describe(descriptions$1.exchangeDeliveryFee),
-	sellerFaultFreeShipping: z.boolean().optional().describe(descriptions$1.sellerFaultFreeShipping),
-	conditionalFreeShortfallCharge: z.boolean().optional().describe(descriptions$1.conditionalFreeShortfallCharge)
-});
-/**
-* 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
-*
-* 반품비·교환비는 레거시 필드(`products.returnFee`·`exchangeFee`)와 **연결**한다. 상품이
-* `refundPolicy.returnDeliveryFee`를 정하면 그 값이 원천이고(서버가 `returnFee`도 같은 값으로 맞춘다),
-* 정하지 않았으면 레거시 값이 0보다 클 때 그 값을 쓴다. 0이면 스토어 기본을 따른다 —
-* 정책이 생기기 전에 만든 상품(반품비 0)이 스토어 기본을 물려받게 하는 규칙이다.
-*/
-function resolveRefundPolicy(storePolicy, product) {
-	return {
-		...REFUND_POLICY_DEFAULTS,
-		...dropUndefined(storePolicy),
-		...productRefundPolicyOverride(product) ?? {}
-	};
-}
-/**
-* 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
-*
-* `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
-* 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
-* 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
-*/
-function productRefundPolicyOverride(product) {
-	const override = dropUndefined(product?.refundPolicy);
-	const legacy = {};
-	if (override.returnDeliveryFee === void 0 && (product?.returnFee ?? 0) > 0) legacy.returnDeliveryFee = product?.returnFee ?? 0;
-	if (override.exchangeDeliveryFee === void 0 && (product?.exchangeFee ?? 0) > 0) legacy.exchangeDeliveryFee = product?.exchangeFee ?? 0;
-	const merged = {
-		...legacy,
-		...override
-	};
-	if (product?.refundPolicy == null && Object.keys(merged).length === 0) return null;
-	return merged;
-}
-/** `undefined` 값을 빼고 얕게 복사한다 — 전개 순서로 덮어쓸 때 `undefined`가 기본값을 지우지 않게 */
-function dropUndefined(patch) {
-	if (!patch) return {};
-	return Object.fromEntries(Object.entries(patch).filter(([, value]) => value !== void 0));
-}
-/**
-* 수량 단위 부분 취소의 환불 기준액 — **누적 내림의 차분**이다.
-*
-* 원 단위 반올림 규칙: `floor(주문상품 금액 × 누적 수량 ÷ 전체 수량)`을 두 번 구해 그 차를 쓴다.
-* 부분 취소를 몇 번 나눠도 합이 주문상품 금액과 정확히 같아서 1원이 남거나 넘치지 않는다.
-* 할인은 이미 단가에 들어 있어(주문 단위 쿠폰이 없다) 별도 안분이 없다.
-*
-* @param totalPrice 주문상품 금액 (할인 반영 단가 × 전체 수량)
-* @param quantity 주문상품 전체 수량
-* @param settledQuantity 이미 취소·반품된 누적 수량
-* @param cancelQuantity 이번에 취소·반품할 수량
-*/
-function proratedRefundBase(totalPrice, quantity, settledQuantity, cancelQuantity) {
-	if (quantity <= 0 || cancelQuantity <= 0) return 0;
-	const before = Math.floor(totalPrice * settledQuantity / quantity);
-	const after = Math.floor(totalPrice * (settledQuantity + cancelQuantity) / quantity);
-	return Math.max(0, after - before);
-}
-//#endregion
 //#region src/schemas/upload.ts
 /**
 * 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
 *
 * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
 * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+* - `digital-asset`: 파일 다운로드 상품의 판매 파일(이슈 #48). **비공개 객체**로 올라가고 공개 주소가 없다 — 구매자는 제공된
+*   주문상품에서 수명 300초의 서명 주소로만 받는다.
 */
-const uploadPurposeSchema = z.enum(["product-image", "description"]);
+const uploadPurposeSchema = z.enum([
+	"product-image",
+	"description",
+	"digital-asset"
+]);
 const MB = 1048576;
 /**
 * 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
@@ -2261,8 +3300,35 @@ const UPLOAD_PURPOSE_LIMITS = {
 			"mov"
 		],
 		maxBytes: 50 * MB
+	},
+	"digital-asset": {
+		extensions: [
+			"pdf",
+			"epub",
+			"zip",
+			"mp3",
+			"wav",
+			"flac",
+			"m4a",
+			"mp4",
+			"mov",
+			"jpg",
+			"jpeg",
+			"png",
+			"webp",
+			"psd",
+			"ai",
+			"txt",
+			"csv",
+			"xlsx",
+			"docx",
+			"pptx"
+		],
+		maxBytes: 200 * MB
 	}
 };
+/** 비공개 업로드(판매 파일)의 PUT 필수 헤더 — CDN이 이 값으로 공개 조회를 막는다 */
+const PRIVATE_UPLOAD_HEADERS = { "x-amz-meta-visibility": "private" };
 /** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
 function uploadExtensionOf(filename) {
 	const dot = filename.lastIndexOf(".");
@@ -2300,10 +3366,12 @@ const uploadRequestSchema = z.object({
 	size: z.number().int().positive().optional().describe("파일 바이트 크기. 주면 용도별 상한을 발급 전에 검사한다")
 });
 const uploadTicketSchema = z.object({
-	/** 업로드 완료 후 공개될 주소 */
+	/** 업로드 완료 후 공개될 주소. 비공개 업로드(`digital-asset`)는 이 주소로 받을 수 없다 */
 	url: z.url(),
 	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
-	uploadUrl: z.url()
+	uploadUrl: z.url(),
+	key: z.string().optional().describe("객체 키. 비공개 업로드(`digital-asset`)는 이 값으로 상품에 파일을 연결한다(`POST /v1/products/{productId}/digital-assets`). 공개 업로드에는 없다"),
+	headers: z.record(z.string(), z.string()).optional().default({}).describe("PUT에 반드시 실을 헤더. 비공개 업로드는 `x-amz-meta-visibility: private`이고 빠뜨리면 공개 객체가 된다. 공개 업로드는 빈 객체다")
 });
 //#endregion
 //#region src/schemas/product.ts
@@ -2330,6 +3398,7 @@ const productSummarySchema = z.object({
 	thumbnailUrl: z.url().optional(),
 	/** optionGroups.length > 0 */
 	hasOptions: z.boolean(),
+	fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
 	updatedAt: z.string()
 });
 /** 옵션 축(그룹)이 가지는 값 하나 — 예: 축 "색상"의 값 "블랙" */
@@ -2364,6 +3433,28 @@ const productVariantSchema = z.object({
 	sellerCode: z.string().nullable(),
 	usable: z.boolean()
 });
+const discountSchema = z.object({
+	productId: z.string(),
+	discountType: z.enum(["RATE", "AMOUNT"]),
+	discountValue: z.number().int(),
+	discountedPrice: z.number().int(),
+	startAt: z.string().nullable(),
+	endAt: z.string().nullable()
+});
+/**
+* 상품 유형 응답 필드 (이슈 #48) — 이 필드 이전 서버의 응답에는 없으므로 기본값을 둔다. 서버는 항상 싣는다.
+*/
+function productFulfillmentResponseShape() {
+	return {
+		fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
+		fulfillmentMode: z.string().nullable().optional().default(null).describe("제공 방식. `AUTO`(결제 확정과 함께 제공)·`MANUAL`(셀러가 제공 처리). 배송 상품은 null. 값이 추가될 수 있어 문자열로 받는다"),
+		stockTracking: z.boolean().optional().default(true).describe("재고를 세는가. false면 재고와 무관하게 판다(파일 다운로드 기본)"),
+		downloadLimit: z.number().int().nullable().optional().default(null).describe("파일 다운로드 횟수 한도. 파일 다운로드 상품이 아니면 null"),
+		downloadDays: z.number().int().nullable().optional().default(null).describe("파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품이 아니면 null"),
+		withdrawalRestricted: z.boolean().optional().default(false).describe("청약철회 제한 대상인가. 파일 다운로드·코드 발급 상품만 켤 수 있다(그 밖의 유형은 false로 저장한다). true면 주문서에서 제한 고지에 대한 구매자 동의를 받고, 첫 다운로드·열람 뒤 구매자 취소·반품을 받지 않는다"),
+		pickupAddressId: z.string().nullable().optional().default(null).describe("방문 수령지 주소 id(`seller_addresses`, 유형 PICKUP). 방문 수령 상품이 아니면 null")
+	};
+}
 const productSchema = productSummarySchema.extend({
 	description: z.string().optional(),
 	/**
@@ -2385,9 +3476,15 @@ const productSchema = productSummarySchema.extend({
 	conditionalFreeAmount: z.number().int().nullable().optional(),
 	returnFee: z.number().int().optional(),
 	exchangeFee: z.number().int().optional(),
-	refundPolicy: refundPolicyPatchSchema.nullable().optional().describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
+	refundPolicy: productRefundPolicyPatchSchema.nullable().optional().describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
 	shippingAddressId: z.string().nullable().optional(),
 	returnAddressId: z.string().nullable().optional(),
+	...productFulfillmentResponseShape(),
+	/**
+	* 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
+	* 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
+	*/
+	discount: discountSchema.nullable().optional().describe("설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null"),
 	createdAt: z.string().optional()
 });
 /** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
@@ -2523,6 +3620,23 @@ const ADDRESS_DESCRIPTIONS = {
 	patchShipping: "출고지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
 	patchReturn: "반품지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다"
 };
+/**
+* 상품 유형 요청 필드 (이슈 #48) — 등록·전체 수정·부분 수정이 같은 필드를 받는다.
+*
+* 생략의 뜻: 등록은 배송 상품(`SHIPPING`)과 유형 기본값이고, 전체 수정(PUT)·부분 수정(PATCH)은 **현재 값을 유지**한다.
+* 이 필드를 모르는 옛 클라이언트가 전체 수정을 보내도 유형이 배송 상품으로 되돌아가지 않게 한다.
+*/
+function productFulfillmentRequestShape() {
+	return {
+		fulfillmentType: fulfillmentTypeSchema.optional().describe("상품 유형. `SHIPPING` 배송 상품 · `DOWNLOAD` 파일 다운로드 · `CODE` 코드 발급 · `SERVICE` 이용권·서비스 · `PICKUP` 방문 수령. 등록에서 생략하면 SHIPPING이고, 수정에서 생략하면 바꾸지 않는다. 판매 이력이 있는 상품의 유형은 바꿀 수 없다(409 `FULFILLMENT_TYPE_LOCKED`). 배송 상품이 아니면 배송비·출고지·반품지·반품비·교환비를 무시하고 0·null로 저장한다"),
+		fulfillmentMode: fulfillmentModeSchema.nullable().optional().describe("제공 방식. `AUTO` 결제 확정과 함께 제공 · `MANUAL` 셀러가 제공 처리. 생략·null이면 유형 기본값이다(코드 발급 AUTO, 이용권 MANUAL, 파일 다운로드 AUTO만, 방문 수령 MANUAL만). 배송 상품은 무시한다"),
+		stockTracking: z.boolean().optional().describe("재고를 세는가. 파일 다운로드 상품만 끌 수 있다(기본 false). 그 밖의 유형은 항상 true"),
+		downloadLimit: z.number().int().min(1).max(100).nullable().optional().describe("파일 다운로드 횟수 한도. 파일 다운로드 상품만 쓰고 생략·null이면 5회"),
+		downloadDays: z.number().int().min(1).max(3650).nullable().optional().describe("파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품만 쓰고 생략·null이면 30일"),
+		withdrawalRestricted: z.boolean().optional().describe("청약철회 제한 대상인가. true면 주문서가 제한 고지를 보여 주고 구매자 동의를 받는다. 배송 상품은 false로 저장한다"),
+		pickupAddressId: z.string().nullable().optional().describe("방문 수령지 주소 id(`GET /v1/seller-addresses?type=PICKUP`). 방문 수령 상품만 쓴다. 생략하면 스토어 기본 방문 수령지를 저장한다")
+	};
+}
 const productCreateRequestSchema = z.object({
 	name: z.string().min(1).max(100),
 	categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
@@ -2544,9 +3658,10 @@ const productCreateRequestSchema = z.object({
 	conditionalFreeAmount: z.number().int().optional().describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
 	returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위. `refundPolicy.returnDeliveryFee`와 같은 값이다"),
 	exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위. `refundPolicy.exchangeDeliveryFee`와 같은 값이다"),
-	refundPolicy: refundPolicyPatchSchema.nullish().describe("상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. `returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다"),
+	refundPolicy: productRefundPolicyPatchSchema.nullish().describe("상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. `returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다"),
 	shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.shipping),
-	returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return)
+	returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return),
+	...productFulfillmentRequestShape()
 }).extend(optionModelRequestSchema.shape);
 const productPatchRequestSchema = z.object({
 	name: z.string().max(100).optional(),
@@ -2554,7 +3669,8 @@ const productPatchRequestSchema = z.object({
 	status: productStatusSchema.optional(),
 	deliveryFee: z.number().int().optional(),
 	shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchShipping),
-	returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn)
+	returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn),
+	...productFulfillmentRequestShape()
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 const productSortSchema = z.enum([
 	"createdAt.desc",
@@ -2572,14 +3688,6 @@ const productListQuerySchema = z.object({
 	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
 	...pageQueryShape()
 });
-const discountSchema = z.object({
-	productId: z.string(),
-	discountType: z.enum(["RATE", "AMOUNT"]),
-	discountValue: z.number().int(),
-	discountedPrice: z.number().int(),
-	startAt: z.string().nullable(),
-	endAt: z.string().nullable()
-});
 const discountRequestSchema = z.object({
 	discountType: z.enum(["RATE", "AMOUNT"]),
 	discountValue: z.number().int().min(1),
@@ -2606,6 +3714,9 @@ const discountRequestSchema = z.object({
 *
 * 계산은 `quoteDelivery` 하나다. 장바구니·주문서·결제 시작·환불 정산이 모두 이 함수를 쓴다 —
 * 네 곳이 각자 계산하면 화면 금액과 결제 금액이 갈라진다.
+*
+* **비실물 줄은 배송 계산에서 빠진다**(이슈 #48, `requiresShipping`). 묶음을 만들지 않고, 스토어 전체 무료 기준의
+* 판정 금액(`shippableAmount`)에도 넣지 않는다 — 디지털 상품 금액이 실물 배송비를 면제시키지 않게 한다.
 */
 const descriptions = {
 	baseDeliveryFee: "스토어 기본 배송비. 원 단위. 상품 등록·수정에서 `deliveryFee`를 생략하면 이 값을 쓴다. 기본 3000",
@@ -2978,11 +4089,12 @@ function quoteDelivery(input) {
 	const area = remoteAreaOf(input.zipCode);
 	const surcharge = remoteSurchargeOf(policy, area);
 	const groups = /* @__PURE__ */ new Map();
-	let productAmount = 0;
+	let shippableAmount = 0;
 	for (const line of input.lines) {
 		const product = input.productOf(line.productId);
 		if (!product) continue;
-		productAmount += line.amount;
+		if (!requiresShipping(line.fulfillmentType ?? product.fulfillmentType)) continue;
+		shippableAmount += line.amount;
 		const key = deliveryBundleKeyOf(product);
 		const group = groups.get(key) ?? {
 			product,
@@ -2993,7 +4105,7 @@ function quoteDelivery(input) {
 		group.sum += line.amount;
 		groups.set(key, group);
 	}
-	const freeByThreshold = policy.freeThreshold !== null && productAmount >= policy.freeThreshold && groups.size > 0;
+	const freeByThreshold = policy.freeThreshold !== null && shippableAmount >= policy.freeThreshold && groups.size > 0;
 	const bundles = [];
 	for (const [bundleKey, group] of groups) {
 		const { product } = group;
@@ -3018,7 +4130,9 @@ function quoteDelivery(input) {
 		remoteSurcharge,
 		deliveryFee: baseFee + remoteSurcharge,
 		remoteArea: area,
-		freeByThreshold
+		freeByThreshold,
+		shippableAmount,
+		requiresShipping: bundles.length > 0
 	};
 }
 //#endregion
@@ -3118,6 +4232,8 @@ const updateStoreRequestSchema = z.object({
 	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프론트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
 	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프론트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
 	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다"),
+	fulfillmentMailEnabled: z.boolean().optional().describe("비실물 상품 제공 안내 메일(이슈 #48). 켜면(기본) 제공이 끝났을 때 구매자에게 안내 메일을 보낸다. 코드·파일 주소는 싣지 않는다"),
+	withdrawalNotice: z.string().trim().min(1).max(1e3).nullable().optional().describe("청약철회 제한 고지 문구(이슈 #48). 제한 상품이 있는 주문서에 보인다. null이면 플랫폼 기본 문구를 쓴다"),
 	autoDeliverDays: z.number().int().min(0).max(30).optional().describe(autoDeliverDaysDescription),
 	autoConfirmDays: z.number().int().min(0).max(30).optional().describe(autoConfirmDaysDescription),
 	refundPolicy: refundPolicyPatchSchema.optional().describe("스토어 기본 환불 정책 — 준 항목만 바꾼다. 상품별 정책(`products.refundPolicy`)이 없는 상품에 적용된다"),
@@ -3143,6 +4259,8 @@ const storeSchema = z.object({
 	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
 	storefrontOrigins: z.array(z.string()).describe("스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
 	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+	fulfillmentMailEnabled: z.boolean().optional().default(true).describe("비실물 상품 제공 안내 메일(이슈 #48). 서버는 항상 싣는다"),
+	withdrawalNotice: z.string().nullable().optional().default(null).describe("청약철회 제한 고지 문구(이슈 #48). null이면 플랫폼 기본 문구다. 서버는 항상 싣는다"),
 	autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
 	autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
 	refundPolicy: refundPolicySchema.describe("스토어 기본 환불 정책. 스토어가 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다"),
@@ -3213,7 +4331,15 @@ const storeMemberRoleUpdatedSchema = z.object({
 	userId: z.string(),
 	role: z.enum(["ADMIN", "STAFF"])
 });
-const addressTypeSchema = z.enum(["SHIPPING", "RETURN"]);
+/**
+* 주소 유형 — 출고지·반품지·방문 수령지(이슈 #48). 방문 수령지(`PICKUP`)는 목록에서 `type=PICKUP`으로 조회할 때만 나온다
+* (이 값을 모르는 옛 SDK의 목록 파싱이 깨지지 않게).
+*/
+const addressTypeSchema = z.enum([
+	"SHIPPING",
+	"RETURN",
+	"PICKUP"
+]);
 /** `GET /v1/seller-addresses` 쿼리 — OpenAPI 문서용 형태. 기본 주소 우선, 그다음 등록순이다 */
 const sellerAddressListQuerySchema = z.object({ type: addressTypeSchema.optional().describe("주소 유형 필터") });
 const sellerAddressSchema = z.object({
@@ -3387,7 +4513,10 @@ function createStoreClient(options) {
 				}) });
 				const put = await fetchFn(ticket.uploadUrl, {
 					method: "PUT",
-					headers: { "content-type": file.type || "application/octet-stream" },
+					headers: {
+						...ticket.headers,
+						"content-type": file.type || "application/octet-stream"
+					},
 					body: file
 				});
 				if (!put.ok) throw new ApiError(put.status, "UPLOAD_PUT_FAILED", `업로드에 실패했습니다: ${filename}`);
@@ -3422,8 +4551,37 @@ function createStoreClient(options) {
 			updateVariantStock: (productId, variantId, body) => storeHttp.request("PATCH", path`/products/${productId}/variants/${variantId}/stock`, variantStockSchema, { body: variantStockRequestSchema.parse(body) }),
 			getDiscount: (productId) => storeHttp.request("GET", path`/products/${productId}/discount`, discountSchema),
 			setDiscount: (productId, body) => storeHttp.request("PUT", path`/products/${productId}/discount`, discountSchema, { body: discountRequestSchema.parse(body) }),
-			removeDiscount: (productId) => storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`)
+			removeDiscount: (productId) => storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
+			/**
+			* 코드 일괄 업로드 (이슈 #48) — 코드 발급·자동 제공 상품의 코드 풀에 올린다. `codes`와 `csv` 중 하나만 보낸다.
+			* 받은 코드 수만큼 재고가 는다. 에러: 409 `NOT_CODE_PRODUCT`·`CODE_POOL_NOT_USED`·`CODE_UPLOAD_CONFLICT`, 400 `TOO_MANY_CODES`
+			*/
+			uploadCodes: (productId, body, idempotencyKey) => storeHttp.request("POST", path`/products/${productId}/codes`, fulfillmentCodeBatchSchema, {
+				body: fulfillmentCodeUploadRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			/** 코드 목록 — 가린 값(`hint`)만 싣는다. `available`은 필터와 무관한 판매 가능 코드 수다 */
+			listCodes: (productId, params) => storeHttp.request("GET", path`/products/${productId}/codes`, fulfillmentCodePageSchema, { query: params }),
+			/** 판매 가능 코드 폐기 — 재고가 1 준다. 배정된 코드는 409 `CODE_NOT_AVAILABLE` */
+			voidCode: (productId, codeId) => storeHttp.request("POST", path`/products/${productId}/codes/${codeId}/void`, fulfillmentCodeSchema),
+			/**
+			* 판매 파일 연결 (이슈 #48) — `uploads.create({ purpose: "digital-asset" })`로 받은 `key`에 파일을 올린 뒤 연결한다.
+			* 이후 주문부터 이 파일을 준다. 에러: 400 `INVALID_ASSET_KEY`, 409 `NOT_DOWNLOAD_PRODUCT`·`ASSET_ALREADY_ATTACHED`
+			*/
+			attachDigitalAsset: (productId, body) => storeHttp.request("POST", path`/products/${productId}/digital-assets`, digitalAssetSchema, { body: digitalAssetAttachRequestSchema.parse(body) }),
+			/** 판매 파일 목록 — 해제한 파일도 싣는다. 객체 키·주소는 없다 */
+			listDigitalAssets: (productId) => storeHttp.request("GET", path`/products/${productId}/digital-assets`, z.array(digitalAssetSchema)),
+			/** 판매 파일 해제 — 새 주문에 주지 않는다. 이미 산 구매자는 계속 받는다 */
+			removeDigitalAsset: (productId, assetId) => storeHttp.request("DELETE", path`/products/${productId}/digital-assets/${assetId}`, digitalAssetSchema),
+			/** 판매 파일 확인 주소 — 수명 300초의 서명 주소 */
+			previewDigitalAsset: (productId, assetId) => storeHttp.request("POST", path`/products/${productId}/digital-assets/${assetId}/preview-url`, digitalAssetPreviewSchema)
 		},
+		fulfillmentCodes: { 
+		/**
+		* 코드 평문 열람 — 콘솔에서 로그인한 OWNER·ADMIN만 된다(403 `INSUFFICIENT_ROLE`). 열람 기록과 감사 로그가 남는다.
+		* 평문은 화면에 보인 뒤 저장하지 않는다
+		*/
+reveal: (codeId) => storeHttp.request("POST", path`/fulfillment-codes/${codeId}/reveal`, fulfillmentCodeRevealSchema) },
 		categories: {
 			list: (params) => storeHttp.request("GET", "/categories", z.array(categorySchema), { query: params }),
 			tree: () => storeHttp.request("GET", "/categories", z.array(categoryTreeNodeSchema), { query: { tree: true } }),
@@ -3489,6 +4647,27 @@ function createStoreClient(options) {
 				body: { orderItemIds },
 				headers: idempotency(idempotencyKey)
 			}),
+			/**
+			* 제공 안내 메일 재발송 (이슈 #48) — 제공된 주문상품의 안내 메일을 다시 보낸다. 주문상품당 하루 3회(429).
+			* 코드·파일 주소는 메일에 없다
+			*/
+			resendFulfillmentMail: (orderItemId) => storeHttp.request("POST", path`/order-items/${orderItemId}/fulfillment/mail`, fulfillmentMailResendSchema),
+			/**
+			* 제공 처리 (이슈 #48) — 수동 제공 비실물 주문상품(이용권·방문 수령)을 `PAID`·`CONFIRMED`에서 제공 완료(`DELIVERED`)로
+			* 바꾼다. `note`는 구매자 주문 상세에 이용 안내로 실린다. 배송 상품은 409 `SHIPPING_REQUIRED`
+			*/
+			fulfill: (orderItemId, body = {}, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/fulfill`, orderItemSchema, {
+				body: fulfillRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			/** 제공 처리 일괄 — 항목별 부분 성공이다 */
+			fulfillBulk: (orderItemIds, body = {}, idempotencyKey) => storeHttp.request("POST", "/order-items/fulfill", bulkResultSchema, {
+				body: fulfillBulkRequestSchema.parse({
+					orderItemIds,
+					...body
+				}),
+				headers: idempotency(idempotencyKey)
+			}),
 			getDelivery: (orderItemId) => storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema)
 		},
 		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
@@ -3540,8 +4719,33 @@ function createStoreClient(options) {
 			orders: (customerId, params) => storeHttp.request("GET", path`/customers/${customerId}/orders`, pageSchema(customerOrderSchema), { query: params }),
 			/** 동의 이력 — 최근 순. 가입·재동의·마케팅 변경이 한 줄씩 남는다 */
 			consents: (customerId, params) => storeHttp.request("GET", path`/customers/${customerId}/consents`, pageSchema(customerConsentSchema), { query: params }),
+			/** 보유 쿠폰 (이슈 #47) — 최근 지급 순, 최대 500장 */
+			coupons: (customerId) => storeHttp.request("GET", path`/customers/${customerId}/coupons`, z.array(customerCouponSchema)),
 			withdraw: (customerId, body) => storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, { body: withdrawCustomerRequestSchema.parse(body) })
 		},
+		/** 쿠폰 (이슈 #47) — 조회 `promotion:r`, 쓰기 `promotion:rw` */
+		coupons: {
+			list: (params) => storeHttp.request("GET", "/coupons", pageSchema(couponSchema), { query: params }),
+			create: (body, idempotencyKey) => storeHttp.request("POST", "/coupons", couponSchema, {
+				body: createCouponRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			get: (couponId) => storeHttp.request("GET", path`/coupons/${couponId}`, couponSchema),
+			update: (couponId, body) => storeHttp.request("PATCH", path`/coupons/${couponId}`, couponSchema, { body: updateCouponRequestSchema.parse(body) }),
+			pause: (couponId) => storeHttp.request("POST", path`/coupons/${couponId}/pause`, couponSchema),
+			resume: (couponId) => storeHttp.request("POST", path`/coupons/${couponId}/resume`, couponSchema),
+			end: (couponId) => storeHttp.request("POST", path`/coupons/${couponId}/end`, couponSchema),
+			/** 셀러 지급 — 한 번에 1,000명까지. 한도에 걸린 구매자는 `failed`에 담긴다 */
+			issue: (couponId, body, idempotencyKey) => storeHttp.request("POST", path`/coupons/${couponId}/issues`, issueCouponResultSchema, {
+				body: issueCouponRequestSchema.parse(body),
+				headers: idempotency(idempotencyKey)
+			}),
+			issues: (couponId, params) => storeHttp.request("GET", path`/coupons/${couponId}/issues`, pageSchema(couponIssueSchema), { query: params }),
+			redemptions: (couponId, params) => storeHttp.request("GET", path`/coupons/${couponId}/redemptions`, pageSchema(couponRedemptionSchema), { query: params }),
+			stats: (couponId) => storeHttp.request("GET", path`/coupons/${couponId}/stats`, couponStatsSchema),
+			/** 발급 쿠폰 회수 — 사용 가능한 발급 쿠폰만 */
+			revokeIssue: (issueId) => storeHttp.request("POST", path`/coupon-issues/${issueId}/revoke`, couponIssueSchema)
+		},
 		customerInquiries: {
 			list: (params) => storeHttp.request("GET", "/customer-inquiries", pageSchema(sellerCustomerInquirySchema), { query: params }),
 			get: (inquiryId) => storeHttp.request("GET", path`/customer-inquiries/${inquiryId}`, sellerCustomerInquirySchema),
@@ -3889,7 +5093,8 @@ const STORE_SCOPE_RESOURCES = {
 	store: ["r", "rw"],
 	member: ["r", "rw"],
 	customer: ["r", "rw"],
-	audit: ["r"]
+	audit: ["r"],
+	promotion: ["r", "rw"]
 };
 const storeScopeResourceSchema = z.enum(Object.keys(STORE_SCOPE_RESOURCES)).describe("스코프 리소스");
 /** 카탈로그상 존재하는 스코프 문자열인가 (예: `settlement:rw`는 false) */
@@ -3917,7 +5122,8 @@ const STORE_ROLE_SCOPES = {
 		"store:rw",
 		"member:rw",
 		"customer:rw",
-		"audit:r"
+		"audit:r",
+		"promotion:rw"
 	],
 	ADMIN: [
 		"product:rw",
@@ -3931,7 +5137,8 @@ const STORE_ROLE_SCOPES = {
 		"store:rw",
 		"member:rw",
 		"customer:rw",
-		"audit:r"
+		"audit:r",
+		"promotion:rw"
 	],
 	STAFF: [
 		"product:rw",
@@ -3940,7 +5147,8 @@ const STORE_ROLE_SCOPES = {
 		"claim:rw",
 		"inquiry:rw",
 		"review:rw",
-		"customer:r"
+		"customer:r",
+		"promotion:r"
 	]
 };
 //#endregion
@@ -3986,12 +5194,30 @@ const mcpToolEventSchema = z.object({
 const envelopeFields = {
 	id: z.string().describe("이벤트 ID (`evt_…`, 테스트 전송은 `evt_test_…`). 중복 제거 키"),
 	createdAt: z.string().describe("이벤트 발생 일시 (ISO 8601)"),
-	storeId: z.string().describe("이벤트가 발생한 스토어 ID")
+	storeId: z.string().describe("이벤트가 발생한 스토어 ID"),
+	sequence: z.number().int().positive().optional().describe("리소스별 순번. 같은 주문·클레임·문의·리뷰·상품의 이벤트마다 1씩 커진다. 도착 순서는 보장하지 않으므로 같은 리소스의 이벤트는 이 값으로 정렬한다. 이 필드가 생기기 전의 이벤트와 테스트 전송에는 없다")
 };
 const orderWebhookEventDataSchema = z.object({
 	orderId: z.string().describe("주문 ID"),
 	status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
-	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다")
+	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다"),
+	couponDiscountAmount: z.number().int().optional().default(0).describe("주문이 받은 상품·주문 쿠폰 할인 합계 (원). 즉시할인(`discountAmount`)과 별개다. 쿠폰이 없거나 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+	orderItemId: z.string().optional().describe("이벤트를 만든 주문상품 ID. 비실물 상품 제공으로 보내는 `ORDER.DELIVERED`에만 실린다. 택배 배송완료와 그 밖의 주문 이벤트에는 없다"),
+	fulfillmentType: z.string().optional().describe("이벤트를 만든 주문상품의 상품 유형. 비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 이 값이 `SHIPPING`이 아니다. 현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. 비실물 제공이 아닌 이벤트에는 없고, 없으면 `SHIPPING`으로 읽는다")
+});
+/**
+* `ORDER.FULFILLED` — 비실물 주문상품(파일·코드·이용권·방문 수령)을 제공했다(이슈 #48). 자동 제공은 결제 확정과 함께,
+* 수동 제공은 셀러의 제공 처리(`POST /v1/order-items/{orderItemId}/fulfill`)로 온다. 기존 구독자를 위해 같은 순간
+* `ORDER.DELIVERED`도 함께 보낸다. **코드·파일 주소는 싣지 않는다** — 관리 API로 조회한다.
+*/
+const orderFulfilledWebhookEventDataSchema = z.object({
+	orderId: z.string().describe("주문 ID"),
+	orderItemId: z.string().describe("제공한 주문상품 ID"),
+	status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
+	fulfillmentType: z.string().describe("상품 유형. 현재 값은 `DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다"),
+	fulfillmentMode: z.string().nullable().describe("제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리)"),
+	fulfilledAt: z.string().describe("제공 시각 (ISO 8601). 주문상품의 `deliveredAt`과 같다"),
+	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다")
 });
 /**
 * `ORDER.CANCELED` — 셀러 직권취소(`POST /v1/order-items/{orderItemId}/cancel`)로 주문상품이 취소됐다.
@@ -4006,9 +5232,11 @@ const orderCanceledWebhookEventDataSchema = z.object({
 	reason: z.string().describe("취소 사유 코드 — 판매자 취소 요청의 `reason`(`OUT_OF_STOCK`·`PRICE_ERROR`·`DELIVERY_IMPOSSIBLE`·`ETC`). 사유가 늘어날 수 있어 문자열이다. 모르는 값은 `ETC`처럼 다룬다"),
 	quantity: z.number().int().describe("이번에 취소한 수량"),
 	canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
-	refundAmount: z.number().int().describe("환불액 (원). 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감이다. 결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다"),
+	refundAmount: z.number().int().describe("환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`)이다. 결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다"),
 	deliveryFeeRefundAmount: z.number().int().describe("환불액에 포함된 배송비 (원)"),
 	deliveryFeeChargeAmount: z.number().int().describe("환불액에서 뺀 배송비 (원) — 조건부 무료배송 기준 미달 차감"),
+	couponChargeAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 취소는 차감하지 않으므로 늘 0이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. 전량 취소면 누적 차감이 모두 되돌아간다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	testPayment: z.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다")
 });
 const claimWebhookEventDataSchema = z.object({
@@ -4022,6 +5250,8 @@ const claimWebhookEventDataSchema = z.object({
 	deliveryFeeRefundAmount: z.number().int().optional().default(0).describe("환불액에 포함된 배송비 (원). 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	deliveryFeeChargeAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 배송비 (원) — 반품·교환 배송비와 조건부 무료배송 미달 차감의 합. 셀러가 승인에 넣은 추가 차감은 `deductAmount`로 따로 온다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	deductAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 추가 차감 (원) — 셀러가 클레임 승인에 넣은 금액이다(상품 훼손 등). 배송비 차감과 별개이므로 `deliveryFeeChargeAmount`와 더해서 뺀다. 접수 이벤트와 이 필드가 없는 이전 이벤트는 0이다"),
+	couponChargeAmount: z.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감 (원) — 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃어 남은 주문상품이 받던 할인을 뺀 금액이다. 배송비 차감·추가 차감과 별개다. 접수 이벤트는 예상값이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+	couponChargeRefundAmount: z.number().int().optional().default(0).describe("환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. 접수 이벤트는 예상값이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문의 클레임인가. 이 필드가 없는 이전 이벤트는 false로 읽는다")
 });
 const inquiryWebhookEventDataSchema = z.object({
@@ -4049,6 +5279,11 @@ const orderWebhookEventSchema = z.object({
 	]),
 	data: orderWebhookEventDataSchema
 });
+const orderFulfilledWebhookEventSchema = z.object({
+	...envelopeFields,
+	type: z.literal("ORDER.FULFILLED"),
+	data: orderFulfilledWebhookEventDataSchema
+});
 const orderCanceledWebhookEventSchema = z.object({
 	...envelopeFields,
 	type: z.literal("ORDER.CANCELED"),
@@ -4082,6 +5317,7 @@ const productOutOfStockWebhookEventSchema = z.object({
 /** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
 const webhookEventSchema = z.discriminatedUnion("type", [
 	orderWebhookEventSchema,
+	orderFulfilledWebhookEventSchema,
 	orderCanceledWebhookEventSchema,
 	claimWebhookEventSchema,
 	inquiryWebhookEventSchema,
@@ -4238,4 +5474,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, CASH_RECEIPT_STATUS_VALUES, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_VALUES_PER_GROUP, MAX_VARIANTS, MCP_TELEMETRY_MAX_RESULTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, REFUND_POLICY_DEFAULTS, REMOTE_AREA_ZIP_RANGES, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, UPLOAD_PURPOSE_LIMITS, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_FAILURE_REASONS, WEBHOOK_HEADERS, WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES, WEBHOOK_RESOURCE_TYPES, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, agentPolicyDecisionSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, consentActionSchema, consentKindSchema, consentSourceSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, mcpRuleResultSchema, mcpToolEventSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedRefundBase, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, resolveRefundPolicy, resolveShippingPolicy, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema };
+export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, CASH_RECEIPT_STATUS_VALUES, COUPON_CODE_PATTERN, COUPON_CONDITIONS_DEFAULTS, COUPON_TARGET_ALL, COUPON_TARGET_LIST_MAX, FULFILLMENT_RULES, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_CODES_PER_UPLOAD, MAX_CODE_LENGTH, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_VALUES_PER_GROUP, MAX_VARIANTS, MCP_TELEMETRY_MAX_RESULTS, MIN_PAYMENT_AMOUNT, NO_COUPON_SETTLEMENT, NO_SHIPPING_BUNDLE_KEY, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, PRIVATE_UPLOAD_HEADERS, REFUND_POLICY_DEFAULTS, REMOTE_AREA_ZIP_RANGES, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, UPLOAD_PURPOSE_LIMITS, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_FAILURE_REASONS, WEBHOOK_HEADERS, WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES, WEBHOOK_RESOURCE_TYPES, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, agentPolicyDecisionSchema, allocateByWeight, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, consentActionSchema, consentKindSchema, consentSourceSchema, couponBenefitSchema, couponConditionsInputSchema, couponConditionsSchema, couponDiscountOf, couponIssueListQuerySchema, couponIssueMethodSchema, couponIssueSchema, couponIssueStatusSchema, couponKindSchema, couponListQuerySchema, couponRedemptionListQuerySchema, couponRedemptionSchema, couponRejectReasonSchema, couponRuleSchema, couponSchema, couponStatsSchema, couponStatusSchema, couponTargetInputSchema, couponTargetSchema, createCouponRequestSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerCouponSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, digitalAssetAttachRequestSchema, digitalAssetPreviewSchema, digitalAssetSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, fulfillBulkRequestSchema, fulfillRequestSchema, fulfillmentCodeBatchSchema, fulfillmentCodeListQuerySchema, fulfillmentCodePageSchema, fulfillmentCodeRejectionSchema, fulfillmentCodeRevealSchema, fulfillmentCodeSchema, fulfillmentCodeStatusSchema, fulfillmentCodeUploadRequestSchema, fulfillmentMailResendSchema, fulfillmentModeSchema, fulfillmentRuleOf, fulfillmentTypeOf, fulfillmentTypeResponseSchema, fulfillmentTypeSchema, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isCouponTargetLine, isReservedStoreCode, isStoreScope, isWebOrigin, issueCouponRequestSchema, issueCouponResultSchema, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, mcpRuleResultSchema, mcpToolEventSchema, myAccountSchema, myStoreSchema, normalizeCouponCode, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderDiscountSchema, orderFulfilledWebhookEventDataSchema, orderFulfilledWebhookEventSchema, orderItemCodeSchema, orderItemDownloadSchema, orderItemFulfillmentSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productRefundPolicyPatchSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedPaidRefundBase, proratedRefundBase, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, quotePricing, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, requiresCollection, requiresShipping, resolveFulfillmentMode, resolveRefundPolicy, resolveShippingPolicy, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settleCouponShortfall, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateCouponRequestSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema };