@sayren/store-sdk 0.28.3 → 0.29.0

package/dist/index.mjs

@@ -903,6 +903,174 @@ const approveClaimResultSchema = z.object({
 	refundedAt: z.string()
 });
 //#endregion
+//#region src/schemas/fulfillment.ts
+/**
+* 상품 유형 (이슈 #48·#57) — 배송이 필요한 상품과 필요 없는 상품을 가르는 축이다.
+*
+* **상품 유형은 이행 방식 하나로 표현한다.** `fulfillment.type`이 배송 필요 여부, 이행 흐름, 클레임 규칙을 정한다.
+* 코드 곳곳에서 유형 이름으로 분기하지 않고 이 파일의 판정 함수(`requiresShipping`·`fulfillmentRuleOf`)를 지난다.
+*
+* 주문상품 상태 enum은 바꾸지 않는다. 비실물의 **제공 완료는 `DELIVERED`를 재사용한다** — 새 상태를 더하면 기존 소비자의
+* 상태 분기(배송완료 뒤 구매확정 대기, 반품 가능 판정)가 새 값을 모른다. 표시는 유형으로 가른다.
+*/
+/**
+* 상품 유형.
+* - `SHIPPING` 배송 상품. 택배로 발송하고 송장·배송 추적으로 배송완료가 된다
+* - `MANUAL` 배송 없는 상품(비실물). 셀러가 제공 처리(`POST /v1/order-items/{orderItemId}/fulfill`)로 제공 완료를 기록한다
+*
+* 비실물의 세부 구분(파일 다운로드·코드 발급·이용권·방문 수령)은 2026-09-28에 제품에서 뺐다(이슈 #48 범위 축소).
+* 이름은 이행 방식이다 — `SHIPPING`이 택배 발송이듯 `MANUAL`은 셀러가 직접 제공한다는 뜻이다.
+*/
+const fulfillmentTypeSchema = z.enum(["SHIPPING", "MANUAL"]);
+/**
+* 응답 스키마용 유형 — 서버가 나중에 유형을 더해도 옛 SDK가 응답 파싱에서 깨지지 않게 문자열로 받는다.
+* 요청은 `fulfillmentTypeSchema`(닫힌 enum)로 검증한다.
+*/
+const fulfillmentTypeResponseSchema = z.string().describe("상품 유형. 현재 값은 `SHIPPING`(배송 상품)·`MANUAL`(배송 없는 상품, 셀러가 제공 처리)이고 값이 추가될 수 있어 문자열로 받는다");
+/** 유형별 규칙표 — **유일한 원천이다.** */
+const FULFILLMENT_RULES = {
+	SHIPPING: {
+		requiresShipping: true,
+		requiresCollection: true,
+		exchangeSupported: true
+	},
+	MANUAL: {
+		requiresShipping: false,
+		requiresCollection: false,
+		exchangeSupported: false
+	}
+};
+/**
+* 저장된 값 → 유형. null·모르는 값은 `SHIPPING`이다 — 이 필드 이전의 상품·주문상품은 모두 배송 상품이었다.
+*/
+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;
+}
+/**
+* 배송이 없는 주문상품의 배송 묶음 키 (`order_items.delivery_bundle_key`).
+*
+* null로 두면 환불 정산이 #29 이전 주문의 레거시 폴백(「묶음 = 같은 상품」, 상품의 **현재** 배송비)을 탄다.
+* 이 키를 만나면 배송비 환불·차감이 0이고 `orders.delivery_fee_settlements`에 항목을 만들지 않는다.
+* 정책 지문 키(`b:…`)와 겹치지 않는다.
+*/
+const NO_SHIPPING_BUNDLE_KEY = "none";
+/** 배송비 유형 — 무료·유료·조건부 무료 */
+const deliveryTypeSchema = z.enum([
+	"FREE",
+	"PAID",
+	"CONDITIONAL_FREE"
+]);
+const KNOWN_FULFILLMENT_TYPES = fulfillmentTypeSchema.options;
+const ADDRESS_ID_DESCRIPTIONS = {
+	shipping: "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 등록에서 생략하면 그 시점 상점 기본 출고지를 저장한다. `null`이면 비워 둔다(상점 기본 출고지를 따른다). 이 상점의 `SHIPPING` 주소가 아니면 거부한다",
+	return: "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 등록에서 생략하면 그 시점 상점 기본 반품지를 저장한다. `null`이면 비워 둔다(상점 기본 반품지를 따른다). 이 상점의 `RETURN` 주소가 아니면 거부한다"
+};
+/**
+* 배송비 필드 사이의 일관성 — FREE의 배송비, 조건부 무료가 아닌 상품의 무료 기준을 조용히 0·null로 바꿔 저장하지 않고 400으로 돌려준다
+* (셀러가 저장됐다고 믿는 값이 사라지지 않게). 조건부 무료는 기준 금액이 필수다 — 기준 없는 조건부 무료는 계산상 유료 배송이다.
+*/
+function refineShippingConsistency(value, ctx) {
+	if (value.deliveryType === "FREE" && value.deliveryFee !== void 0 && value.deliveryFee !== 0) ctx.addIssue({
+		code: "custom",
+		path: ["deliveryFee"],
+		message: "무료 배송(FREE)의 배송비는 0이거나 생략해야 합니다"
+	});
+	const threshold = value.conditionalFreeAmount;
+	const hasThreshold = threshold !== void 0 && threshold !== null;
+	if (value.deliveryType === "CONDITIONAL_FREE" && !hasThreshold) ctx.addIssue({
+		code: "custom",
+		path: ["conditionalFreeAmount"],
+		message: "조건부 무료(CONDITIONAL_FREE)는 무료 기준 금액이 필요합니다"
+	});
+	if (value.deliveryType !== "CONDITIONAL_FREE" && hasThreshold) ctx.addIssue({
+		code: "custom",
+		path: ["conditionalFreeAmount"],
+		message: "무료 기준 금액은 조건부 무료(CONDITIONAL_FREE)에서만 받습니다"
+	});
+}
+const deliveryTypeDescription = "배송비 유형. `FREE` 무료, `PAID` 유료, `CONDITIONAL_FREE` 조건부 무료";
+const shippingCreateSchema = z.strictObject({
+	deliveryType: deliveryTypeSchema.default("PAID").describe(deliveryTypeDescription),
+	deliveryFee: z.number().int().min(0).optional().describe("배송비. 원 단위. 생략하면 상점 기본 배송비(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 저장한다. FREE면 0이거나 생략한다"),
+	conditionalFreeAmount: z.number().int().min(0).nullable().optional().describe("무료 배송이 되는 묶음 소계. 원 단위. CONDITIONAL_FREE에서만 받고 필수다"),
+	shippingAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
+	returnAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.return)
+}).superRefine(refineShippingConsistency);
+/**
+* 상품 이행 — 등록(POST). 배송 상품의 `shipping`을 생략하면 기본값(유료 배송·상점 기본 배송비·기본 출고지·반품지)이다.
+*/
+const productFulfillmentCreateSchema = z.discriminatedUnion("type", [z.strictObject({
+	type: z.literal("SHIPPING"),
+	shipping: shippingCreateSchema.optional()
+}), z.strictObject({ type: z.literal("MANUAL") })]);
+const shippingUpdateSchema = z.strictObject({
+	deliveryType: deliveryTypeSchema.describe(deliveryTypeDescription),
+	deliveryFee: z.number().int().min(0).describe("배송비. 원 단위. FREE면 0"),
+	conditionalFreeAmount: z.number().int().min(0).nullable().describe("무료 배송이 되는 묶음 소계. CONDITIONAL_FREE면 필수, 아니면 null"),
+	shippingAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
+	returnAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.return)
+}).superRefine(refineShippingConsistency);
+/**
+* 상품 이행 — 수정(PUT·PATCH). 통째 교체이고 유형 키와 그 안의 필드가 **모두 필수**다. 서버는 현재 값과 병합하지 않는다.
+* `fulfillment` 자체를 생략하면 이행을 바꾸지 않는다.
+*/
+const productFulfillmentUpdateSchema = z.discriminatedUnion("type", [z.strictObject({
+	type: z.literal("SHIPPING"),
+	shipping: shippingUpdateSchema
+}), z.strictObject({ type: z.literal("MANUAL") })]);
+/**
+* 저장된 상품 이행 — 알려진 유형의 닫힌 유니온. 서버의 상품 엔티티와 응답이 이 모양을 쓴다.
+* 응답 파싱은 `productFulfillmentResponseSchema`(열린 유니온)를 쓴다.
+*/
+const productFulfillmentSchema = z.discriminatedUnion("type", [z.object({
+	type: z.literal("SHIPPING"),
+	shipping: z.object({
+		deliveryType: deliveryTypeSchema,
+		deliveryFee: z.number().int().describe("배송비. 원 단위. FREE면 0"),
+		conditionalFreeAmount: z.number().int().nullable().describe("조건부 무료 기준 묶음 소계. CONDITIONAL_FREE가 아니면 null"),
+		shippingAddressId: z.string().nullable().describe("출고지 주소 id. null이면 상점 기본 출고지를 따른다"),
+		returnAddressId: z.string().nullable().describe("반품지 주소 id. null이면 상점 기본 반품지를 따른다")
+	})
+}), z.object({ type: z.literal("MANUAL") })]);
+/**
+* 열린 응답 유니온 — 알려진 유형은 판별 유니온으로 검사하고, **모르는 유형만** `{ type: "OTHER", rawType }`로 읽는다.
+*
+* `type: z.string()` 가지를 그대로 두면 TS가 `type === "SHIPPING"`으로 좁혀도 문자열 가지가 남는다. `OTHER` 리터럴로 바꿔 좁히기를
+* 지킨다. 알려진 유형의 모양이 틀린 응답은 폴백으로 숨기지 않고 파싱 오류로 둔다.
+*/
+function openFulfillmentUnion(known) {
+	return z.union([known, z.looseObject({ type: z.string().refine((type) => !KNOWN_FULFILLMENT_TYPES.includes(type), { message: "알려진 유형은 해당 유형의 모양이어야 합니다" }) }).transform((value) => ({
+		type: "OTHER",
+		rawType: value.type
+	}))]);
+}
+const productFulfillmentResponseSchema = openFulfillmentUnion(productFulfillmentSchema).describe("상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 값이 추가될 수 있어 SDK는 모르는 유형을 `{ type: \"OTHER\", rawType }`로 읽는다");
+/**
+* 주문상품의 주문 시점 이행 — 결제 확정이 주문서 줄에서 굳힌다. 상품의 현재 값이 아니다. 서버는 주문상품 컬럼
+* (`fulfillment_type`·`delivery_bundle_key`)과 jsonb(`fulfillment_snapshot`)를 합쳐 이 모양을 만든다.
+*/
+const orderItemFulfillmentSnapshotSchema = z.discriminatedUnion("type", [z.object({
+	type: z.literal("SHIPPING"),
+	shipping: z.object({
+		bundleKey: z.string().nullable().describe("배송 묶음 키. 같은 키의 주문상품이 배송비를 한 번 낸 한 묶음이다. #29 이전 주문은 null"),
+		returnAddressId: z.string().nullable().describe("주문 시점 반품지 주소 id. null이거나 지워진 주소면 상점 기본 반품지로 안내한다")
+	})
+}), z.object({ type: z.literal("MANUAL") })]);
+const orderItemFulfillmentSnapshotResponseSchema = openFulfillmentUnion(orderItemFulfillmentSnapshotSchema).describe("주문 시점 이행 스냅샷. 상품을 나중에 고쳐도 바뀌지 않는다. 제공 기록은 `fulfillment`에 있다. 값이 추가될 수 있어 SDK는 모르는 유형을 `OTHER`로 읽는다");
+//#endregion
 //#region src/schemas/refund-policy.ts
 /**
 * 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
@@ -1016,2257 +1184,2271 @@ function proratedRefundBase(totalPrice, quantity, settledQuantity, cancelQuantit
 	return Math.max(0, after - before);
 }
 //#endregion
-//#region src/schemas/promotion.ts
+//#region src/schemas/upload.ts
 /**
-* 쿠폰 금액 계산 (이슈 #47) — 쿠폰 할인을 **얼마나, 어느 주문상품에** 주는지를 정한다.
-*
-* 계산은 순수 함수 `quotePricing` 하나다. 장바구니 요약, 주문서 미리보기, 결제 시작의 최종 확정,
-* 주문 스냅샷, 환불 정산의 조건 미달 판정(`settleCouponShortfall`)이 모두 이 함수를 지난다.
-* 다섯 경로가 각자 계산하면 화면 금액, 결제 금액, 환불 금액이 갈라진다(`quoteDelivery`와 같은 원칙).
-*
-* 계산 순서
-* 1. 즉시할인(`products.discount`)은 이미 단가에 들어 있다. 입력 `amount`가 즉시할인 반영 금액이다.
-* 2. 상품 쿠폰(`PRODUCT`) — 주문상품 한 줄에 한 장. 그 줄 금액을 기준으로 할인한다.
-* 3. 주문 쿠폰(`ORDER`) — 주문에 한 장. **상품 쿠폰 차감 뒤 금액**의 대상 합계를 기준으로 할인하고,
-*    대상 줄에 금액 비율로 나눈다(누적 내림의 차분).
-* 4. 배송비 쿠폰(`DELIVERY`) — 주문에 한 장. 기본 배송비(지역 추가 배송비 제외)를 기준으로 할인하고
-*    배송 묶음에 기본 배송비 비율로 나눈다.
+* 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
 *
-* 무료배송 기준(상품별 조건부 무료·상점 전체 기준)은 **쿠폰 차감 전 금액**으로 판정한다. 그래서 배송비
-* 견적(`quoteDelivery`)은 쿠폰과 무관하게 먼저 계산되고, 이 함수는 그 결과만 입력으로 받는다.
+* - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
+* - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+*/
+const uploadPurposeSchema = z.enum(["product-image", "description"]);
+const MB = 1048576;
+/**
+* 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
 *
-* 최소 주문 금액은 대상 상품의 **즉시할인 반영 합계**(쿠폰 차감 전, 배송비 제외)로 판정한다.
-* 정률 할인은 10원 단위로 내리고(`discountedPriceOf`의 즉시할인과 같은 단위), 최대 할인액과 기준 금액을
-* 넘지 않는다.
+* 크기는 **요청이 스스로 신고한 값**으로만 검사한다. 바이트는 api를 거치지 않고 CDN으로
+* 직접 PUT되므로 이 검사는 셀러가 올리기 전에 알게 하는 장치이고, 실제 상한은 CDN이 강제한다.
 */
-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 UPLOAD_PURPOSE_LIMITS = {
+	"product-image": {
+		extensions: [
+			"jpg",
+			"jpeg",
+			"png",
+			"webp",
+			"avif",
+			"gif"
+		],
+		maxBytes: 10 * MB
+	},
+	description: {
+		extensions: [
+			"jpg",
+			"jpeg",
+			"png",
+			"gif",
+			"webp",
+			"avif",
+			"svg",
+			"mp4",
+			"webm",
+			"mov"
+		],
+		maxBytes: 50 * MB
+	}
 };
-/** 쿠폰 종류 */
-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: "정액 할인에는 최대 할인액을 두지 않습니다"
-	});
+/** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
+function uploadExtensionOf(filename) {
+	const dot = filename.lastIndexOf(".");
+	if (dot < 0 || dot === filename.length - 1) return "";
+	return filename.slice(dot + 1).toLowerCase();
+}
+/**
+* 용도 제한 위반 여부. 통과하면 `null`.
+* 서버가 던지는 오류와 상점 플랫폼이 먼저 띄우는 안내가 갈리지 않도록 한 함수로 판정한다.
+*/
+function uploadRejection(purpose, filename, size) {
+	const limit = UPLOAD_PURPOSE_LIMITS[purpose];
+	if (!limit.extensions.includes(uploadExtensionOf(filename))) return {
+		status: 400,
+		code: "UNSUPPORTED_FILE_TYPE",
+		message: `지원하지 않는 파일 형식입니다. ${limit.extensions.join(", ")}만 올릴 수 있습니다`
+	};
+	if (size !== void 0 && size > limit.maxBytes) return {
+		status: 413,
+		code: "FILE_TOO_LARGE",
+		message: `파일이 너무 큽니다. ${Math.floor(limit.maxBytes / MB)}MB까지 올릴 수 있습니다`
+	};
+	return null;
+}
+/**
+* 미디어 업로드 자리 발급 — `POST /v1/uploads`.
+*
+* 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
+* 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
+* (확장자만 쓰이고 이름 자체는 저장되지 않는다).
+*/
+const uploadRequestSchema = z.object({
+	filename: z.string().min(1).max(255),
+	purpose: uploadPurposeSchema.default("description").describe("업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다"),
+	size: z.number().int().positive().optional().describe("파일 바이트 크기. 주면 용도별 상한을 발급 전에 검사한다")
 });
-/** 쿠폰 사용 조건 */
-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 uploadTicketSchema = z.object({
+	/** 업로드 완료 후 공개될 주소 */
+	url: z.url(),
+	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
+	uploadUrl: z.url()
 });
-/** 조건을 생략했을 때의 값 */
-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)
+//#endregion
+//#region src/schemas/product.ts
+const productStatusSchema = z.enum([
+	"SALE",
+	"SUSPENDED",
+	"OUT_OF_STOCK",
+	"CLOSED"
+]);
+const productSummarySchema = z.object({
+	productId: z.string(),
+	name: z.string(),
+	status: productStatusSchema,
+	salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
+	discountedPrice: z.number().int().nullable().describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
+	/** usable variant 재고 합계 (서버 계산) */
+	stockQuantity: z.number().int().describe("판매 가능한 옵션 재고의 합계. 서버가 계산한다"),
+	categoryId: z.string().nullable(),
+	thumbnailUrl: z.url().optional(),
+	/** optionGroups.length > 0 */
+	hasOptions: z.boolean(),
+	fulfillment: z.object({ type: fulfillmentTypeResponseSchema }).describe("상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다"),
+	updatedAt: z.string(),
+	sample: z.boolean().optional().default(false).describe("상점을 만들 때 넣은 샘플 상품인가(이슈 #70). 상점 플랫폼이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다")
+});
+/** 옵션 축(그룹)이 가지는 값 하나 — 예: 축 "색상"의 값 "블랙" */
+const optionValueSchema = z.object({
+	valueId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int()
+});
+/** 옵션 축(그룹) — 예: "색상", "사이즈" */
+const optionGroupSchema = z.object({
+	groupId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int(),
+	values: z.array(optionValueSchema)
 });
-const COUPON_TARGET_ALL = {
-	includeProductIds: [],
-	includeCategoryIds: [],
-	excludeProductIds: [],
-	excludeCategoryIds: []
-};
 /**
-* 쿠폰 규칙 스냅샷 — 계산에 필요한 값만 담는다. 결제 시작이 쿠폰을 읽어 이 형태로 결제 세션에 굳히고,
-* 주문 생성·환불 정산은 이 스냅샷만 읽는다. 결제 도중·주문 뒤 셀러가 쿠폰을 바꿔도 그 주문의 금액은 움직이지 않는다.
+* 판매 단위(SKU). variantId는 기존 optionId 값 공간을 승계하므로
+* 카트·주문·리뷰·클레임의 optionId가 곧 variantId다.
 */
-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 productVariantSchema = z.object({
+	variantId: z.string(),
+	/** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
+	valueIds: z.array(z.string()),
+	/** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
+	name: z.string(),
+	additionalPrice: z.number().int(),
+	stockQuantity: z.number().int(),
+	sku: z.string().nullable(),
+	barcode: z.string().nullable(),
+	costPrice: z.number().int().nullable(),
+	weightGram: z.number().int().nullable(),
+	sellerCode: z.string().nullable(),
+	usable: z.boolean(),
+	hasOrders: z.boolean().optional().describe("주문에 담긴 적이 있는 조합인가(이슈 #59). true인 조합은 옵션 교체에서 뺄 수 없고(409 `OPTION_HAS_ORDERS`) `usable: false`로 판매를 끈다. 서버는 항상 싣는다. 요청에는 쓰지 않는다")
 });
-/** 쿠폰을 적용하지 못한 사유 */
-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",
-	"LINE_AMBIGUOUS",
-	"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`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, `LINE_AMBIGUOUS`=지정한 `optionId`의 줄이 여럿이라 줄을 정할 수 없음(`lineId`로 지목한다), `NO_DISCOUNT`=할인할 금액이 없음");
-/** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
-const MIN_PAYMENT_AMOUNT = 100;
+/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
+const MAX_OPTION_GROUPS = 3;
+/** 축 하나가 가질 수 있는 값의 최대 개수 */
+const MAX_VALUES_PER_GROUP = 100;
+/** 상품 하나가 가질 수 있는 variant(SKU) 최대 개수 */
+const MAX_VARIANTS = 500;
+/** 추가 선택 옵션명 최대 개수 */
+const MAX_ADDON_GROUPS = 5;
+/** 직접 입력 항목 최대 개수 */
+const MAX_CUSTOM_INPUTS = 5;
+/** 직접 입력 항목 최대 글자 수의 상한 */
+const MAX_CUSTOM_INPUT_LENGTH = 200;
+/** 조합 수가 이 값 이상이면 상점 플랫폼이 경고한다(상한은 `MAX_VARIANTS`) */
+const VARIANT_COUNT_WARNING = 100;
 /**
-* 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
-*
-* 곱셈을 먼저 하고 나눈다. `base × 율 ÷ 1000`을 내려 10을 곱하면 `floor(base × 율 / 100 / 10) × 10`과 같고
-* 부동소수 오차가 끼지 않는다.
+* 옵션 값 정렬 순서 — 등록순·가나다순·낮은 추가금순·높은 추가금순. 서버가 저장할 때 이 순서로 값의 `sortOrder`를 매긴다.
+* 추가금순은 추가 선택 값이면 값의 추가금, 조합 값이면 그 값이 든 조합 추가금의 최솟값으로 비교하고 같으면 등록순이다.
 */
-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));
-}
+const optionSortSchema = z.enum([
+	"REGISTERED",
+	"NAME",
+	"PRICE_ASC",
+	"PRICE_DESC"
+]);
+/** 추가 선택 값 — 예: 옵션명 "선물 포장"의 값 "포장함"(+2,000원) */
+const addonValueSchema = z.object({
+	valueId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int(),
+	additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
+	usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 고를 수 없다")
+});
+/** 추가 선택 옵션명 */
+const addonGroupSchema = z.object({
+	groupId: z.string(),
+	name: z.string(),
+	sortOrder: z.number().int(),
+	required: z.boolean().describe("구매자가 꼭 골라야 하는가. false면 고르지 않아도 된다"),
+	values: z.array(addonValueSchema)
+});
+/** 직접 입력 항목 — 예: 각인 문구 */
+const customInputSchema = z.object({
+	inputId: z.string(),
+	label: z.string().describe("항목명"),
+	placeholder: z.string().nullable().describe("입력 안내(구매자 입력 칸의 안내 문구). 없으면 null"),
+	maxLength: z.number().int().describe("최대 글자 수"),
+	required: z.boolean(),
+	usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않는다"),
+	sortOrder: z.number().int()
+});
 /**
-* 금액을 가중치 비율로 나눈다 — **누적 내림의 차분**이다.
-*
-* `i`번째 몫 = `floor(total × W_i / W) − floor(total × W_{i−1} / W)`(`W_i`는 앞에서부터 누적 가중치).
-* 합이 `total`과 정확히 같고, 입력 순서가 같으면 결과도 같다. `total ≤ W`이면 몫이 가중치를 넘지 않는다.
-* 곱이 2^53을 넘을 수 있어 BigInt로 계산한다.
+* 직접 입력 항목명에 쓸 수 없는 개인정보성 단어 — 상점 플랫폼 검사와 서버 400(`CUSTOM_INPUT_LABEL_FORBIDDEN`)이 이 목록 하나를 쓴다.
+* 구매자 개인정보는 주문 정보로 받는다. 직접 입력 항목으로 받으면 보관·파기 규칙 밖에 남는다.
 */
-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);
+const CUSTOM_INPUT_FORBIDDEN_WORDS = [
+	"연락처",
+	"전화",
+	"휴대폰",
+	"핸드폰",
+	"폰번호",
+	"메일",
+	"주소",
+	"주민",
+	"생년월일",
+	"생일",
+	"실명",
+	"계좌",
+	"카드번호",
+	"비밀번호",
+	"여권",
+	"통관",
+	"phone",
+	"mobile",
+	"mail",
+	"address"
+];
+/** 금지어 비교용 정규화 — NFKC(전각·호환 문자를 보통 문자로)·소문자 뒤 문자·숫자만 남긴다(공백·기호·제로폭 문자로 쪼갠 우회를 막는다) */
+function forbiddenWordKeyOf(text) {
+	return text.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
 }
 /**
-* 사용 기간 판정 — 쿠폰 기간과 발급 쿠폰 유효 기간 중 좁은 쪽. 시작은 포함, 종료는 제외.
-* 읽지 못하는 시각은 제한 없음이 아니라 거절이다(fail-closed).
+* 직접 입력 항목명·입력 안내에 든 개인정보성 금지어. 없으면 null. 공백·기호·대소문자·전각을 무시한다.
+* 서버는 항목명과 입력 안내 둘 다 이 함수로 검사한다(안내에 「연락처를 적어 주십시오」라고 쓰는 우회를 막는다).
 */
-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;
+function customInputLabelForbiddenWord(label) {
+	const normalized = forbiddenWordKeyOf(label);
+	return CUSTOM_INPUT_FORBIDDEN_WORDS.find((word) => normalized.includes(forbiddenWordKeyOf(word))) ?? null;
 }
+/** 옵션명·값 이름 — 앞뒤 공백을 지우고 빈 값은 받지 않는다 */
+const optionNameSchema = z.string().trim().min(1).max(50);
+const addonValueRequestSchema = z.object({
+	/** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
+	valueId: z.string().optional(),
+	name: optionNameSchema,
+	additionalPrice: z.number().int().min(0).default(0).describe("추가금(원, 0 이상)"),
+	usable: z.boolean().default(true)
+});
+const addonGroupRequestSchema = z.object({
+	/** 전달 시 기존 옵션명 행을 유지(UPDATE). 조합 옵션명의 id는 줄 수 없다(방식을 바꾸려면 새 옵션명으로 보낸다) */
+	groupId: z.string().optional(),
+	name: optionNameSchema,
+	required: z.boolean().default(false),
+	values: z.array(addonValueRequestSchema).min(1).max(100)
+});
+const customInputRequestSchema = z.object({
+	/** 전달 시 기존 항목 행을 유지(UPDATE). 생략하면 신규 발급 */
+	inputId: z.string().optional(),
+	label: z.string().trim().min(1).max(30),
+	placeholder: z.string().trim().max(100).nullish(),
+	maxLength: z.number().int().min(1).max(200),
+	required: z.boolean().default(false),
+	usable: z.boolean().default(true)
+});
 /**
-* 쿠폰 금액 계산 — **순수 함수다.** DB를 읽지 않는다. 규칙 스냅샷을 만드는 조회와 한도·보유 판정
-* (발급 쿠폰 상태, 1인 한도)은 호출부 몫이다.
+* 주문상품·장바구니·주문서 줄의 옵션 선택 스냅샷 한 칸 — 주문 시점 이름이다(상품을 고쳐도 바뀌지 않는다).
+* 조합 옵션은 옵션명마다 한 칸이고 추가금은 조합 단위라 0이다(조합 추가금은 단가에 들어 있다). 추가 선택은 값의 추가금이다.
+*/
+const optionSelectionSchema = z.object({
+	kind: z.string().describe("옵션명 방식. 현재 값은 `combination`·`addon`이고 값이 추가될 수 있어 문자열로 받는다"),
+	groupName: z.string(),
+	valueName: z.string(),
+	additionalPrice: z.number().int()
+});
+/** 구매자가 적은 직접 입력값 — 주문 시점 항목명과 값 */
+const customInputValueSchema = z.object({
+	label: z.string(),
+	value: z.string()
+});
+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 productSchema = productSummarySchema.extend({
+	description: z.string().optional(),
+	/**
+	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+	*/
+	descriptionJson: z.string().nullable().optional(),
+	originalPrice: z.number().int().nullable().optional().describe("정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액 계산에 쓰지 않는다 — 구매자가 내는 가격은 즉시할인이 있으면 `discountedPrice`, 없으면 `salePrice`다. 스토어프론트 상품 응답에도 같은 값이 실린다. 정하지 않았으면 null"),
+	images: z.array(z.url()).optional(),
+	attributes: z.array(z.object({
+		attributeId: z.string(),
+		value: z.string()
+	})).optional(),
+	optionGroups: z.array(optionGroupSchema),
+	/** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
+	variants: z.array(productVariantSchema),
+	addonGroups: z.array(addonGroupSchema).optional().default([]).describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+	customInputs: z.array(customInputSchema).optional().default([]).describe("직접 입력 항목(이슈 #59). 사용하지 않는 항목도 싣는다. 없으면 빈 배열. 서버는 항상 싣는다"),
+	optionSort: optionSortSchema.optional().default("REGISTERED").describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다"),
+	fulfillment: productFulfillmentResponseSchema,
+	fulfillmentTypeLocked: z.boolean().describe("판매 이력(주문상품)이 있어 상품 유형(`fulfillment.type`)을 바꿀 수 없는가. true면 다른 유형으로 수정하는 요청이 409 `FULFILLMENT_TYPE_LOCKED`다. 같은 유형 안의 속성은 바꿀 수 있다"),
+	refundPolicy: productRefundPolicyPatchSchema.nullable().describe("상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 상점 기본 환불 정책을 쓴다. 반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 있다"),
+	/**
+	* 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
+	* 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
+	*/
+	discount: discountSchema.nullable().optional().describe("설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null"),
+	createdAt: z.string().optional()
+});
+/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
+const MAX_PRODUCT_IMAGES = 10;
+/**
+* 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
 *
-* 종류별로 상품 쿠폰 → 주문 쿠폰 → 배송비 쿠폰 순으로 적용한다. 같은 종류의 자리와 같은 쿠폰 id는
-* **적용된** 쿠폰만 차지한다 — 앞선 주문 쿠폰이 최소 금액 미달이면 뒤의 주문 쿠폰이 쓰이고, 같은 쿠폰의 발급
-* 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
+* https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
+* **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
+* 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
+*
+* 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
+* 만들면 상품 조회 자체가 막힌다.
 */
-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 productImageUrlSchema = z.url().max(2048).describe("상품 이미지 주소. https만 허용하고, 확장자가 있으면 이미지 형식이어야 한다");
+/**
+* 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
+*
+* - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
+*   상세 화면에 박히는 주입 경로가 된다.
+* - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
+* - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
+*   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+*/
+function productImageRejection(url) {
+	if (url.length > 2048) return {
+		code: "INVALID_IMAGE_URL",
+		message: "이미지 주소가 너무 깁니다"
 	};
-	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);
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			code: "INVALID_IMAGE_URL",
+			message: "이미지 주소 형식이 아닙니다"
+		};
+	}
+	if (parsed.protocol !== "https:") return {
+		code: "INVALID_IMAGE_URL",
+		message: "이미지 주소는 https로 시작해야 합니다"
 	};
-	const duplicate = (index) => {
-		const result = results[index];
-		if (!appliedCouponIds.has(result.couponId)) return false;
-		result.rejectReason = "DUPLICATE_COUPON";
-		return true;
+	const extension = uploadExtensionOf(parsed.pathname);
+	const allowed = UPLOAD_PURPOSE_LIMITS["product-image"].extensions;
+	if (extension && !allowed.includes(extension)) return {
+		code: "UNSUPPORTED_FILE_TYPE",
+		message: `상품 이미지는 ${allowed.join(", ")}만 쓸 수 있습니다`
 	};
-	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([
-	"joined_desc",
-	"joined_asc",
-	"total_paid_desc",
-	"order_count_desc",
-	"last_ordered_desc"
-]).describe("정렬. `joined_desc`(기본, 최근 가입순)·`joined_asc`·`total_paid_desc`(구매 금액순)·`order_count_desc`(주문 수순)·`last_ordered_desc`(최근 주문순)");
-/** `GET /v1/customers` 쿼리 */
-const customerListQuerySchema = z.object({
-	q: z.string().optional().describe("검색어 — 이름·이메일(포함). 숫자 4자리면 휴대폰 뒤 4자리로도 찾는다"),
-	joinedFrom: z.string().optional().describe("가입일 시작(YYYY-MM-DD, KST, 포함)"),
-	joinedTo: z.string().optional().describe("가입일 끝(YYYY-MM-DD, KST, 포함)"),
-	marketing: z.enum(["agreed", "declined"]).optional().describe("마케팅 수신 동의 필터. 생략하면 전체"),
-	sort: customerSortSchema.optional(),
-	...pageQueryShape()
-});
-/** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
-const customerStatsSchema = z.object({
-	orderCount: z.number().int().describe("주문 수(취소 포함)"),
-	totalPaid: z.number().int().describe("구매 금액(원) — 취소·완료된 반품 제외"),
-	lastOrderedAt: z.string().nullable().describe("최근 주문 시각")
-});
-/** 목록 행 — 휴대폰은 가운데를 가린다(`010-****-1234`) */
-const customerSummarySchema = z.object({
-	customerId: z.string(),
-	name: z.string(),
-	/** 소셜 가입에서 이메일을 받지 못했으면 null */
-	email: z.string().nullable(),
-	maskedPhone: z.string().nullable(),
-	joinedAt: z.string(),
-	point: z.number().int(),
-	marketingAgreed: z.boolean()
-}).extend(customerStatsSchema.shape);
-const customerAddressSchema = z.object({
-	addressId: z.string(),
-	alias: z.string(),
-	isDefault: z.boolean(),
-	receiverName: z.string(),
-	phone: z.string(),
-	zipCode: z.string(),
-	address1: z.string(),
-	address2: z.string().nullable()
-});
-/** 동의 종류 — 이용약관·개인정보 수집이용은 가입 필수, 마케팅 수신은 선택 */
-const consentKindSchema = z.enum([
-	"TERMS",
-	"PRIVACY",
-	"MARKETING"
-]);
-const consentActionSchema = z.enum(["AGREED", "WITHDRAWN"]);
-/**
-* 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
-* `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
-* `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
-*/
-const consentSourceSchema = z.enum([
-	"SIGNUP",
-	"SOCIAL_SIGNUP",
-	"DELEGATED",
-	"RECONSENT",
-	"MEMBER_UPDATE",
-	"SELLER"
-]);
-/** 동의 이력 한 줄 — 추가만 되고 지워지지 않는다(구매자 탈퇴 시에만 함께 지워진다) */
-const customerConsentSchema = z.object({
-	consentId: z.string(),
-	kind: consentKindSchema,
-	/** 동의한 약관 버전. 마케팅은 버전이 없어 null */
-	version: z.string().nullable(),
-	/** 동의 시점의 약관 문서 주소. 상점이 주소를 정하지 않았거나 마케팅이면 null */
-	documentUrl: z.string().nullable(),
-	action: consentActionSchema,
-	source: consentSourceSchema,
-	occurredAt: z.string()
-});
-/** 종류별 현재 동의 상태 */
-const customerConsentStateSchema = z.object({
-	kind: consentKindSchema,
-	agreed: z.boolean(),
-	/** 동의한 약관 버전. 마케팅이거나 이력이 없으면 null */
-	agreedVersion: z.string().nullable(),
-	/** 상점의 현재 약관 버전. 마케팅은 null */
-	currentVersion: z.string().nullable(),
-	/** 상점이 정한 현재 약관 문서 주소. 정하지 않았거나 마케팅이면 null */
-	currentDocumentUrl: z.string().nullable(),
-	updatedAt: z.string().nullable(),
-	/** 약관이 개정돼 다시 받아야 하는가. 마케팅은 항상 false */
-	reconsentRequired: z.boolean()
-});
-const customerConsentsSchema = z.object({
-	terms: customerConsentStateSchema,
-	privacy: customerConsentStateSchema,
-	marketing: customerConsentStateSchema,
-	/** 필수 동의 중 하나라도 현재 버전이 아니면 true */
-	reconsentRequired: z.boolean()
-});
-/** `GET /v1/customers/{id}/consents` 쿼리 — 최근 순이다 */
-const customerConsentListQuerySchema = z.object({
-	kind: consentKindSchema.optional().describe("동의 종류 필터. 생략하면 전체"),
-	...pageQueryShape()
-});
-/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
-const customerDetailSchema = z.object({
-	customerId: z.string(),
-	name: z.string(),
-	email: z.string().nullable(),
-	phone: z.string().nullable(),
-	joinedAt: z.string(),
-	point: z.number().int(),
-	marketingAgreed: z.boolean(),
-	loginMethods: z.array(z.object({
-		method: z.enum([
-			"password",
-			"kakao",
-			"naver",
-			"google"
-		]),
-		/** 소셜 연결 시각. 비밀번호는 가입 시각 */
-		linkedAt: z.string()
-	})).describe("로그인 방법 — 이메일·비밀번호(`password`)와 연결된 소셜 계정"),
-	consents: customerConsentsSchema.describe("약관·개인정보·마케팅 동의의 현재 상태. 이력은 `GET /v1/customers/{customerId}/consents`"),
-	addresses: z.array(customerAddressSchema),
-	stats: customerStatsSchema.extend({
-		canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),
-		reviewCount: z.number().int(),
-		inquiryCount: z.number().int().describe("상품 문의 + 1:1 문의")
-	})
-});
-/** 구매자의 주문 — 전체 기간 */
-const customerOrderSchema = z.object({
-	orderId: z.string(),
-	orderedAt: z.string(),
-	totalAmount: z.number().int().describe("결제 금액"),
-	testPayment: z.boolean(),
-	items: z.array(z.object({
-		orderItemId: z.string(),
-		productName: z.string(),
-		optionName: z.string().nullable(),
-		quantity: z.number().int(),
-		status: orderItemStatusSchema,
-		claimStatus: z.enum([
-			"CANCEL_REQUESTED",
-			"RETURN_REQUESTED",
-			"EXCHANGE_REQUESTED"
-		]).nullable()
-	}))
-});
-/** `POST /v1/customers/{id}/withdraw` 본문 */
-const withdrawCustomerRequestSchema = z.object({
-	reason: z.enum([
-		"BUYER_REQUEST",
-		"DORMANT",
-		"ABUSE",
-		"OTHER"
-	]).describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
-	memo: z.string().max(200).optional().describe("사유 보충(선택)")
-});
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
-const customerWithdrawalBlockedDetailsSchema = z.object({
-	inProgressOrderItems: z.number().int(),
-	openClaims: z.number().int(),
-	pendingPayments: z.number().int()
-});
-//#endregion
-//#region src/schemas/login.ts
-/** 소셜 로그인 공급자 */
-const loginProviderSchema = z.enum([
-	"kakao",
-	"naver",
-	"google"
-]);
-/** 공급자 연결 상태 — 비밀 값은 앞 4자리만 */
-const loginProviderStatusSchema = z.object({
-	provider: loginProviderSchema,
-	connected: z.boolean(),
-	/** 스토어프론트에서 사용 중인지. 연결 안 됐으면 false */
-	enabled: z.boolean(),
-	clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
-	secretPrefix: z.string().nullable(),
-	lastTestedAt: z.string().nullable(),
-	lastTestOk: z.boolean().nullable(),
-	linkedMemberCount: z.number().int().describe("이 공급자로 연결된 구매자 수"),
-	/** 이 공급자로만 로그인하는 구매자 수 — 연결을 해제하면 로그인할 방법이 없어진다 */
-	onlyMethodMemberCount: z.number().int(),
-	callbackUrl: z.url().describe("공급자 개발자 콘솔에 등록할 리디렉트 URI")
-});
-/** `GET /v1/store/login-settings` */
-const loginSettingsSchema = z.object({
-	passwordLoginEnabled: z.boolean(),
-	/** 비밀번호로만 로그인하는 구매자 수 — 이메일·비밀번호를 끄면 이들은 로그인할 수 없다 */
-	passwordOnlyMemberCount: z.number().int(),
-	storefrontOrigins: z.array(z.string()),
-	providers: z.array(loginProviderStatusSchema)
-});
-/** `PATCH /v1/store/login-settings` */
-const updateLoginSettingsRequestSchema = z.object({ passwordLoginEnabled: z.boolean() });
-/** `PUT /v1/store/auth-providers/{provider}` — 저장 전에 연결 테스트를 한다 */
-const saveLoginProviderRequestSchema = z.object({
-	clientId: z.string().trim().min(1).max(200),
-	clientSecret: z.string().trim().min(1).max(500)
-});
-/** `PATCH /v1/store/auth-providers/{provider}` */
-const updateLoginProviderRequestSchema = z.object({ enabled: z.boolean() });
-/** 연결 테스트 결과 */
-const loginProviderTestSchema = z.object({
-	ok: z.boolean(),
-	/** 실패 이유 — `INVALID_CLIENT`(키가 틀림)·`PROVIDER_UNAVAILABLE`(공급자 응답 없음) */
-	code: z.enum(["INVALID_CLIENT", "PROVIDER_UNAVAILABLE"]).nullable(),
-	testedAt: z.string()
-});
-//#endregion
-//#region src/schemas/misc.ts
-const inquirySchema = z.object({
-	inquiryId: z.string(),
-	productId: z.string(),
-	productName: z.string(),
-	orderItemId: z.string().nullable(),
-	category: z.enum([
-		"PRODUCT",
-		"DELIVERY",
-		"RETURN",
-		"EXCHANGE",
-		"ETC"
-	]),
-	content: z.string(),
-	secret: z.boolean(),
-	writerMaskedName: z.string(),
-	answered: z.boolean(),
-	answer: z.object({
-		content: z.string(),
-		answeredAt: z.string(),
-		modifiedCount: z.number().int().max(1)
-	}).nullable(),
-	createdAt: z.string()
-});
-const customerInquiryCategorySchema = z.enum([
-	"DELIVERY",
-	"RETURN",
-	"EXCHANGE",
-	"PAYMENT",
-	"ETC"
-]);
-/** 셀러 뷰 1:1 문의 — 작성자 마스킹명 + 답변 수정횟수 포함 */
-const sellerCustomerInquirySchema = z.object({
-	inquiryId: z.string(),
-	memberMaskedName: z.string(),
-	category: customerInquiryCategorySchema,
-	title: z.string(),
-	content: z.string(),
-	orderItemId: z.string().nullable(),
-	answered: z.boolean(),
-	answer: z.object({
-		content: z.string(),
-		answeredAt: z.string(),
-		modifiedCount: z.number().int().max(1)
-	}).nullable(),
-	createdAt: z.string()
-});
-const answeredQuery = z.enum(["true", "false"]).optional().describe("답변 여부 필터. `true`면 답변된 문의만, `false`면 미답변만, 생략하면 전부");
-/** `GET /v1/inquiries` 쿼리(상품 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
-const inquiryListQuerySchema = z.object({
-	answered: answeredQuery,
-	productId: z.string().optional().describe("상품 id 필터"),
-	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
-	...pageQueryShape()
-});
-/** `GET /v1/customer-inquiries` 쿼리(1:1 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
-const customerInquiryListQuerySchema = z.object({
-	answered: answeredQuery,
-	category: customerInquiryCategorySchema.optional().describe("문의 유형 필터"),
-	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
-	...pageQueryShape()
-});
-const settlementStatusSchema = z.enum([
-	"SCHEDULED",
-	"PAID",
-	"HELD"
-]);
-const settlementSummarySchema = z.object({
-	settlementId: z.string(),
-	settlementDate: z.string(),
-	payoutDate: z.string().nullable(),
-	status: settlementStatusSchema,
-	totalPaymentAmount: z.number().int(),
-	totalCommission: z.number().int(),
-	totalDeliveryFee: z.number().int(),
-	adjustmentAmount: z.number().int(),
-	settlementAmount: z.number().int(),
-	itemCount: z.number().int()
+	return null;
+}
+/**
+* 식별 코드 — 빈 문자열·공백만 있는 값은 거부한다.
+* `""`를 통과시키면 서버 중복 사전 검사(falsy skip)와 DB partial unique
+* (`WHERE ... is not null`)의 판정이 갈려 409 대신 500이 나간다.
+*/
+const codeSchema = z.string().trim().min(1).max(64);
+const optionValueRequestSchema = z.object({
+	/** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
+	valueId: z.string().optional(),
+	name: z.string().min(1).max(50)
 });
-const settlementDetailSchema = z.object({
-	orderItemId: z.string(),
-	productName: z.string(),
-	settlementType: z.enum([
-		"SALE",
-		"REFUND_DEDUCTION",
-		"ADJUSTMENT"
-	]),
-	paymentAmount: z.number().int(),
-	salesCommission: z.number().int(),
-	paymentCommission: z.number().int(),
-	commissionRate: z.number(),
-	deliveryFee: z.number().int(),
-	settlementAmount: z.number().int(),
-	purchaseDecidedAt: z.string().nullable()
+const optionGroupRequestSchema = z.object({
+	/** 전달 시 기존 축 행을 유지(UPDATE). 생략하면 신규 발급 */
+	groupId: z.string().optional(),
+	name: z.string().min(1).max(50),
+	values: z.array(optionValueRequestSchema).min(1).max(100)
 });
-/** `GET /v1/settlements/{settlementId}` 응답 — 정산 요약 + 상세 내역(`size`건까지) */
-const settlementWithDetailsSchema = settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() });
-/** `GET /v1/settlements` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 정산일 최신순이다 */
-const settlementListQuerySchema = z.object({
-	from: z.string().describe("정산일 조회 시작 (ISO 8601, 포함). 필수"),
-	to: z.string().optional().describe("정산일 조회 끝 (ISO 8601, 포함). 생략하면 from부터 31일. 기간은 최대 31일"),
-	status: settlementStatusSchema.optional().describe("정산 상태 필터"),
-	...pageQueryShape()
+const productVariantRequestSchema = z.object({
+	/** 기존 variant 유지 시 전달. 생략하면 신규 생성 */
+	variantId: z.string().optional(),
+	/** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
+	valueNames: z.array(z.string()).default([]),
+	additionalPrice: z.number().int().default(0),
+	/**
+	* 생략 = 기존 재고 유지 (신규 variant는 0).
+	* 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
+	* 재고만 바꿀 때는 PATCH /products/{id}/variants/{variantId}/stock을 쓴다.
+	*/
+	stockQuantity: z.number().int().min(0).optional(),
+	sku: codeSchema.optional(),
+	barcode: codeSchema.optional(),
+	costPrice: z.number().int().min(0).optional(),
+	weightGram: z.number().int().min(0).optional(),
+	sellerCode: codeSchema.optional(),
+	usable: z.boolean().default(true)
 });
-/** `GET /v1/settlements/{settlementId}` 쿼리 — `size`는 돌려줄 상세 내역 건수다(`page`는 무시) */
-const settlementDetailQuerySchema = z.object(pageQueryShape({
-	defaultSize: 100,
-	maxSize: 300
-}));
-const eventTypeSchema = z.enum([
-	"ORDER.PAID",
-	"ORDER.CONFIRMED",
-	"ORDER.DISPATCHED",
-	"ORDER.DELIVERED",
-	"ORDER.PURCHASE_DECIDED",
-	"ORDER.ADDRESS_CHANGE_REQUESTED",
-	"ORDER.CANCELED",
-	"ORDER.FULFILLED",
-	"CLAIM.CANCEL_REQUESTED",
-	"CLAIM.RETURN_REQUESTED",
-	"CLAIM.EXCHANGE_REQUESTED",
-	"CLAIM.COMPLETED",
-	"INQUIRY.CREATED",
-	"REVIEW.CREATED",
-	"PRODUCT.OUT_OF_STOCK"
-]).describe("웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)");
-const webhookStatusSchema = z.enum(["ACTIVE", "SUSPENDED"]).describe("구독 상태. `ACTIVE`=발송 대상, `SUSPENDED`=24시간 이상 연속 전송 실패로 발송이 정지된 상태. 정지 중 발생한 이벤트는 적재하지 않는다. 재개(`POST /webhooks/{id}/resume`)하거나 구독을 수정하면 ACTIVE로 돌아간다");
-const webhookSchema = z.object({
-	webhookId: z.string(),
-	url: z.url(),
-	eventTypes: z.array(eventTypeSchema),
-	status: webhookStatusSchema,
-	secretPrefix: z.string().describe("서명 시크릿 앞부분(식별용, 서명 검증에 사용할 수 없음). 예: `whsec_1a2b`"),
-	suspendedAt: z.string().nullable().describe("발송이 정지된 일시 (ISO 8601). `ACTIVE`면 null"),
-	createdAt: z.string()
+/** 축 × 값 → variant 전체 교체 요청 (PUT /products/{productId}/options) */
+const optionModelRequestSchema = z.object({
+	optionGroups: z.array(optionGroupRequestSchema).max(3).default([]),
+	variants: z.array(productVariantRequestSchema).min(1).max(500),
+	addonGroups: z.array(addonGroupRequestSchema).max(5).optional().describe("추가 선택 옵션명 전체(이슈 #59). 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 끄려면 빈 배열을 보낸다. 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다"),
+	customInputs: z.array(customInputRequestSchema).max(5).optional().describe("직접 입력 항목 전체(이슈 #59). 배열 순서가 표시 순서다. 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 항목명에 개인정보성 단어(`CUSTOM_INPUT_FORBIDDEN_WORDS`)가 있으면 400 `CUSTOM_INPUT_LABEL_FORBIDDEN`, 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다"),
+	optionSort: optionSortSchema.optional().describe("옵션 값 정렬 순서(이슈 #59). 서버가 이 순서로 값의 `sortOrder`를 다시 매긴다. 생략하면 등록은 `REGISTERED`, 수정은 현재 값이다")
 });
-/** 등록 응답 — 서명 시크릿 평문은 이 응답에서만 노출된다 */
-const webhookCreatedSchema = webhookSchema.extend({ secret: z.string().describe("서명 시크릿 평문. 등록 응답에서만 노출되며 다시 조회할 수 없다") });
-/** 시크릿 교체 응답 */
-const webhookSecretRotatedSchema = z.object({
-	secret: z.string().describe("새 서명 시크릿 평문. 이 응답에서만 노출된다"),
-	oldSecretExpiresAt: z.string().describe("기존 시크릿의 병행 유효 종료 일시 (ISO 8601). 이때까지는 기존 시크릿 서명도 함께 붙는다")
+/** GET /products/{productId}/options 응답 */
+const optionModelSchema = z.object({
+	optionGroups: z.array(optionGroupSchema),
+	variants: z.array(productVariantSchema),
+	addonGroups: z.array(addonGroupSchema).optional().default([]).describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+	customInputs: z.array(customInputSchema).optional().default([]).describe("직접 입력 항목(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
+	optionSort: optionSortSchema.optional().default("REGISTERED").describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다")
 });
-const webhookDeliveryStatusSchema = z.enum([
-	"PENDING",
-	"PENDING_RETRY",
-	"SUCCESS",
-	"FAILED"
-]).describe("전송 상태. `PENDING`=첫 시도 전, `PENDING_RETRY`=실패 후 재시도 대기, `SUCCESS`=2xx 응답 수신, `FAILED`=재시도를 모두 소진했거나 구독 정지로 종료");
-const webhookDeliveryErrorCodeSchema = z.enum([
-	"TIMEOUT",
-	"CONNECTION_FAILED",
-	"BLOCKED_ADDRESS",
-	"NON_2XX",
-	"WEBHOOK_SUSPENDED"
-]).describe("전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨");
 /**
-* 실패 원인 분류의 **현재** 값. 응답 스키마(`webhookFailureReasonSchema`)는 문자열로 열려 있다 —
-* 서버가 값을 더해도 이전 SDK가 목록 파싱에 실패하지 않게 한다(택배 추적 `stage`와 같은 이유).
-* 모르는 값은 `errorCode`로 판단한다.
+* 재고 변경 택일 위반 문구 — SDK `.refine`과 서버 DomainException이 공유하는 단일 원천.
+* 경로에 따라 셀러가 다른 문구를 받지 않게 한다.
 */
-const WEBHOOK_FAILURE_REASONS = [
-	"DNS",
-	"TLS",
-	"TIMEOUT",
-	"CONNECTION",
-	"HTTP_4XX",
-	"HTTP_5XX",
-	"HTTP_OTHER",
-	"SSRF_BLOCKED",
-	"SUSPENDED"
-];
-const webhookFailureReasonSchema = z.string().describe("실패 원인 분류(진단용). 현재 값은 `DNS`=호스트 이름을 주소로 바꾸지 못함, `TLS`=인증서·핸드셰이크 실패, `TIMEOUT`=10초 안에 응답 없음, `CONNECTION`=연결 거부·끊김, `HTTP_4XX`·`HTTP_5XX`=그 대역의 응답, `HTTP_OTHER`=2xx·4xx·5xx가 아닌 응답(리다이렉트 등), `SSRF_BLOCKED`=사설·루프백 등 전송이 허용되지 않는 주소, `SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨. `errorCode`보다 잘게 나눈 값이며 둘은 함께 쓸 수 있다. 값이 추가될 수 있으므로 모르는 값은 `errorCode`로 판단한다");
+const VARIANT_STOCK_EXCLUSIVE_MESSAGE = "stockQuantity 또는 adjustment 중 하나만 전달해야 합니다";
 /**
-* 대상 리소스 종류의 **현재** 값. 응답 스키마는 문자열로 열려 있다(새 이벤트가 새 리소스를 가리킬 수 있다).
+* variant 재고 변경 요청 — 절대값(`stockQuantity`) 또는 증감(`adjustment`) 택일.
+* 서버도 같은 규칙을 400 VALIDATION_FAILED로 검증한다(이중 방어).
 */
-const WEBHOOK_RESOURCE_TYPES = [
-	"ORDER",
-	"CLAIM",
-	"PRODUCT",
-	"REVIEW",
-	"INQUIRY"
-];
-const webhookResourceTypeSchema = z.string().describe("이벤트가 가리키는 리소스 종류. 현재 값은 `ORDER`·`CLAIM`·`PRODUCT`·`REVIEW`·`INQUIRY`이고 값이 추가될 수 있다");
-/** 이벤트가 가리키는 대상 리소스 — 전송 기록을 주문·상품과 잇는 키 */
-const webhookDeliveryResourceSchema = z.object({
-	type: webhookResourceTypeSchema,
-	id: z.string().describe("리소스 ID. 전송 기록 조회의 `resourceId`, API 로그 조회의 `q`로 그대로 넣을 수 있다")
-});
-/** 발송 요청 헤더 한 줄 (값 마스킹) */
-const webhookRequestHeaderSchema = z.object({
-	name: z.string().describe("헤더 이름"),
-	value: z.string().nullable().describe("헤더 값. 서명(`Sayren-Signature`)처럼 비밀이 섞이는 헤더는 이름만 주고 값은 null이다")
-});
-/** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
-const webhookDeliverySchema = z.object({
-	deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
-	eventId: z.string().describe("이벤트 ID. 재시도·재전송해도 같은 이벤트면 같은 값이다. 수신 측 중복 제거 키로 쓴다"),
-	eventType: eventTypeSchema,
-	url: z.string().describe("전송 시점의 대상 URL"),
-	status: webhookDeliveryStatusSchema,
-	responseStatusCode: z.number().int().nullable().describe("마지막 시도의 HTTP 응답 코드. 미시도·연결 실패·타임아웃·차단이면 null"),
-	responseTimeMs: z.number().int().nullable().describe("마지막 시도의 응답 시간(ms). 미시도·연결 실패면 null"),
-	responseBodyExcerpt: z.string().nullable().describe("마지막 시도의 응답 본문 앞부분(최대 4,096자). 응답이 없으면 null. 가린 뒤에 자른다. 키 이름에 `authorization`·`token`·`secret`·`password`·`key`·`signature`·`credential`·`cookie`가 **들어 있으면**(부분 일치, 대소문자 무시. 예: `apiKey`·`access_token`·`keyword`) 그 값을 `***`로 가린다. 값이 객체·배열이면 통째로 가린다. 평문 `Authorization: …` 같은 헤더 줄, `Bearer <토큰>`, 쿼리 형식 `access_token=…`, 끝에서 잘려 닫히지 않은 값도 가린다"),
-	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회. 전송 도중 장애로 결과를 기록하지 못한 시도도 센다"),
-	createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
-	attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
-	nextAttemptAt: z.string().nullable().describe("다음 시도 예정 일시 (ISO 8601). `PENDING`·`PENDING_RETRY`일 때만 값이 있다"),
-	redeliveryOf: z.string().nullable().describe("수동 재전송으로 생긴 기록이면 원본 전송 기록 ID. 아니면 null"),
-	redeliveredAs: z.string().nullable().describe("이 기록을 원본으로 수동 재전송해 생긴 기록의 전송 기록 ID. 아직 재전송하지 않았으면 null. 재전송은 원본당 1회다")
-});
-/** 발송 본문 최대 노출 길이(바이트). 넘으면 잘라 주고 `payloadTruncated`가 true다 */
-const WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES = 16384;
-/** 웹훅 전송 기록 상세 — `GET /webhooks/{id}/deliveries/{deliveryId}`. 목록 항목 + 요청 본문·헤더 */
-const webhookDeliveryDetailSchema = webhookDeliverySchema.extend({
-	payload: z.string().describe(`수신 서버로 보낸 요청 본문 그대로(JSON 문자열). 서명은 이 문자열을 대상으로 계산한다. 최대 ${WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES / 1024}KB까지 주고 넘으면 잘라 준다`),
-	payloadTruncated: z.boolean().describe("본문이 길어서 잘렸으면 true. true면 `payload`는 유효한 JSON이 아니다"),
-	payloadMasked: z.boolean().describe("민감 키 마스킹(`responseBodyExcerpt`와 같은 키 이름 규칙)이 본문을 바꿨으면 true. true면 `payload`는 보낸 본문과 달라 서명을 맞춰 볼 수 없다. 이벤트 본문에는 보통 민감 키가 없어 false다"),
-	requestHeaders: z.array(webhookRequestHeaderSchema).describe("발송 요청에 실은 헤더. 값은 전송 시점 그대로이나 서명 헤더는 이름만 주고 값은 null이다. `Content-Length`는 실제로 보낸 본문(마스킹·자르기 전)의 바이트 수다. 매 시도가 같은 헤더 집합을 쓰고 서명·타임스탬프만 달라진다")
-});
-/** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
-const webhookDeliveryListQuerySchema = z.object({
-	status: webhookDeliveryStatusSchema.optional().describe("전송 상태 필터. 생략하면 전체"),
-	eventType: eventTypeSchema.optional().describe("이벤트 타입 필터. 생략하면 전체"),
-	resourceId: z.string().optional().describe("대상 리소스 ID 필터(정확히 일치). 주문·클레임·상품·리뷰·문의 id를 넣으면 그 리소스의 이벤트만 남는다. 같은 id로 API 로그를 `q`로 검색하면 그 리소스를 건드린 API 요청을 볼 수 있다"),
-	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50). 최신 적재순으로 반환하며 보관 기간은 30일이다")
-});
-/** 실패 건 일괄 재전송 응답 — `POST /webhooks/{id}/deliveries/redeliver-failed` */
-const webhookRedeliverFailedResultSchema = z.object({ queued: z.number().int().min(0).describe("재전송 대기열에 올린 건수. 최근 72시간의 `FAILED` 중 아직 재전송되지 않은 건이 대상이며 최대 500건이다") });
-const webhookTestRequestSchema = z.object({ eventType: eventTypeSchema.describe("샘플 페이로드로 보낼 이벤트 타입") });
-/** 테스트 이벤트 발송 결과 (동기 반환). 재시도·정지 판정·전송 기록이 없다 */
-const webhookTestResultSchema = z.object({
-	responseStatusCode: z.number().int().nullable().describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
-	responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
-	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 null"),
-	failureReason: webhookFailureReasonSchema.nullable().describe("실패 원인 분류. 2xx 응답이면 null"),
-	responseBodyExcerpt: z.string().nullable().describe("응답 본문 앞부분(최대 4,096자). 규칙은 전송 기록의 `responseBodyExcerpt`와 같다. 응답이 없으면 null"),
-	requestHeaders: z.array(webhookRequestHeaderSchema).describe("보낸 요청 헤더. 서명 헤더는 이름만 주고 값은 null이다"),
-	payload: z.string().describe("보낸 요청 본문 그대로(JSON 문자열). 샘플 이벤트다")
+const variantStockRequestSchema = z.object({
+	stockQuantity: z.number().int().min(0).optional(),
+	adjustment: z.number().int().optional()
+}).refine((v) => v.stockQuantity !== void 0 !== (v.adjustment !== void 0), { message: VARIANT_STOCK_EXCLUSIVE_MESSAGE });
+/** PATCH /products/{productId}/variants/{variantId}/stock 응답 */
+const variantStockSchema = z.object({
+	variantId: z.string(),
+	stockQuantity: z.number().int()
 });
-const webhookRequestSchema = z.object({
-	url: z.url().startsWith("https://", "웹훅 URL은 HTTPS만 허용됩니다"),
-	eventTypes: z.array(eventTypeSchema).min(1)
+/** 상품 쓰기 요청의 이미지 목록 — 등록·전체 수정·부분 수정이 같은 항목 형식을 쓴다. 첫 장이 대표(썸네일)다 */
+const productImagesRequestSchema = z.array(productImageUrlSchema).min(1).max(10);
+/**
+* 상품 쓰기 요청의 공통 필드 — 등록(POST)과 전체 수정(PUT)이 같다. 이행(`fulfillment`)만 두 요청의 스키마가 다르다.
+*
+* 최상위가 `strictObject`다. 모르는 필드는 400이다 — 이슈 #57 이전의 평면 필드(`deliveryFee`·`fulfillmentType`·`returnFee` 등)를
+* 보낸 요청이 조용히 무시되지 않게 한다. 옛 필드는 `fulfillment.{유형}.…`과 `refundPolicy`로 옮겼다.
+*/
+const productWriteShape = {
+	name: z.string().min(1).max(100),
+	categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
+	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)").describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+	originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액은 판매가(즉시할인이 있으면 할인 적용가)다. 스토어프론트가 판매가보다 클 때 취소선·할인율로 보인다. 즉시할인은 `PUT /v1/products/{productId}/discount`로 따로 정한다"),
+	description: z.string().optional(),
+	/**
+	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+	*/
+	descriptionJson: z.string().nullable().optional(),
+	images: productImagesRequestSchema.optional().describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
+	attributes: z.array(z.object({
+		attributeId: z.string(),
+		value: z.string()
+	})).optional(),
+	refundPolicy: productRefundPolicyPatchSchema.nullish().describe("상품별 환불 정책 — 준 항목만 상점 기본을 덮어쓴다. `null`이나 생략은 상점 기본을 그대로 쓴다는 뜻이다. 반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)"),
+	...optionModelRequestSchema.shape,
+	sourceOptionSetIds: z.array(z.string()).max(10).optional().describe("쓰기 전용(이슈 #59) — 이 저장으로 옵션을 불러온 저장 옵션 id. 상품 저장과 같은 트랜잭션에서 불러오기 기록을 남겨 저장 옵션의 `importedProductCount`를 센다. 없는 id는 무시한다")
+};
+const productCreateRequestSchema = z.strictObject({
+	...productWriteShape,
+	fulfillment: productFulfillmentCreateSchema.optional().describe("상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 생략하면 배송 상품(기본값)이다. 배송 상품이 아닌 유형은 판매가 열린 유형만 등록할 수 있다(409 `FULFILLMENT_TYPE_NOT_AVAILABLE`)")
 });
-const reviewSchema = z.object({
-	reviewId: z.string(),
-	productId: z.string(),
-	productName: z.string(),
-	orderItemId: z.string(),
-	optionName: z.string().nullable(),
-	rating: z.number().int().min(1).max(5),
-	content: z.string(),
-	images: z.array(z.url()),
-	writerMaskedName: z.string(),
-	blinded: z.boolean(),
-	reply: z.object({
-		content: z.string(),
-		repliedAt: z.string(),
-		updatedAt: z.string().nullable()
-	}).nullable(),
-	createdAt: z.string()
+const fulfillmentUpdateDescription = "상품 이행. 생략하면 바꾸지 않는다. 주면 유형 안 필드를 모두 담아 통째로 바꾼다(현재 값과 병합하지 않는다). 판매 이력이 있으면 유형을 바꿀 수 없다(409 `FULFILLMENT_TYPE_LOCKED`)";
+/** 전체 수정(PUT) — 공통 필드는 등록과 같고, 이행은 생략하면 현재 값 유지, 주면 필드가 모두 필수다 */
+const productReplaceRequestSchema = z.strictObject({
+	...productWriteShape,
+	fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription)
 });
-const reviewSortSchema = z.enum([
+const productPatchRequestSchema = z.strictObject({
+	name: z.string().max(100).optional(),
+	salePrice: z.number().int().multipleOf(10).optional(),
+	status: productStatusSchema.optional(),
+	images: productImagesRequestSchema.optional().describe("상품 이미지 주소 목록. 주면 통째로 바꾼다(현재 목록과 병합하지 않는다). 첫 장이 대표 이미지(썸네일)다. 생략하면 바꾸지 않는다"),
+	fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
+	refundPolicy: productRefundPolicyPatchSchema.nullable().optional().describe("상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 상점 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 상점 기본을 따른다. 생략하면 바꾸지 않는다")
+}).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
+const productSortSchema = z.enum([
 	"createdAt.desc",
 	"createdAt.asc",
-	"rating.asc",
-	"rating.desc"
+	"salePrice.asc",
+	"salePrice.desc",
+	"updatedAt.desc"
 ]);
-/** `GET /v1/reviews` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
-const reviewListQuerySchema = z.object({
-	productId: z.string().optional().describe("상품 id 필터"),
-	rating: z.enum([
-		"1",
-		"2",
-		"3",
-		"4",
-		"5"
-	]).optional().describe("별점 필터 (일치)"),
-	replied: z.enum(["true", "false"]).optional().describe("답글 여부 필터. `true`면 답글 단 리뷰만, `false`면 답글 없는 리뷰만"),
-	hasImage: z.enum(["true", "false"]).optional().describe("`true`면 이미지가 있는 리뷰만"),
-	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
-	sort: reviewSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
+/** `GET /v1/products` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const productListQuerySchema = z.object({
+	status: productStatusSchema.optional().describe("판매 상태 필터"),
+	categoryId: z.string().optional().describe("카테고리 필터 — 하위 카테고리의 상품도 포함"),
+	keyword: z.string().optional().describe("상품명 검색 (포함)"),
+	sellerCode: z.string().optional().describe("판매자 상품코드 — 이 코드가 붙은 variant를 가진 상품"),
+	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
 	...pageQueryShape()
 });
-/** `POST /v1/reviews/{reviewId}/report` 응답(202) — 신고 접수 */
-const reviewReportResultSchema = z.object({
-	reviewId: z.string(),
-	status: z.literal("PENDING_REVIEW")
+const discountRequestSchema = z.object({
+	discountType: z.enum(["RATE", "AMOUNT"]),
+	discountValue: z.number().int().min(1),
+	startAt: z.string().optional(),
+	endAt: z.string().optional()
 });
 //#endregion
-//#region src/schemas/fulfillment.ts
+//#region src/schemas/collection.ts
+/**
+* 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음이다. 카테고리는 상품이 무엇인지를 정하고 상품당 하나지만, 컬렉션은
+* 다대다다. 이벤트·기획전은 기간이 있는 직접 선택 컬렉션이다. 권한은 카테고리와 같다(`category:r`·`category:rw`).
+*
+* 유형은 만들 때 정하고 바꿀 수 없다. 지금은 직접 선택(`MANUAL`)만 만들 수 있다. 조건 자동(`AUTOMATIC`)은 다음 단계에서 열리고,
+* 응답의 `type`은 값이 늘 수 있어 문자열이다.
+*/
+/** 상점당 컬렉션 최대 개수 — 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
+const MAX_COLLECTIONS = 200;
+/** 직접 선택 컬렉션 하나에 담는 상품 최대 개수 — 넘으면 409 `COLLECTION_PRODUCT_LIMIT_EXCEEDED` */
+const MAX_COLLECTION_PRODUCTS = 1e3;
+/** 상품 뒤에 붙이기(`POST /v1/collections/{id}/products`) 한 번에 보내는 상품 최대 개수 */
+const MAX_COLLECTION_PRODUCTS_PER_ADD = 500;
+/** 제목 최대 글자 수 */
+const MAX_COLLECTION_TITLE = 60;
+/** 설명 최대 글자 수 */
+const MAX_COLLECTION_DESCRIPTION = 500;
+/** 주소(slug) 형식 — 영문 소문자·숫자·하이픈, 첫 글자는 영문 소문자나 숫자, 64자까지 */
+const COLLECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동, 아직 만들 수 없다) */
+const COLLECTION_TYPES = ["MANUAL", "AUTOMATIC"];
+/**
+* 상품 정렬 — `MANUAL`은 직접 정한 순서(직접 선택 컬렉션만)다. `BEST_SELLING`(판매량순)은 판매량 집계가 열릴 때 받는다.
+* 저장 값 전체 목록이고, 쓰기에서 받는 값은 `collectionProductSortRequestSchema`다.
+*/
+const COLLECTION_PRODUCT_SORTS = [
+	"MANUAL",
+	"LATEST",
+	"BEST_SELLING",
+	"PRICE_ASC",
+	"PRICE_DESC",
+	"REVIEW_COUNT",
+	"RATING_DESC",
+	"RECOMMEND"
+];
+const collectionProductSortRequestSchema = z.enum([
+	"MANUAL",
+	"LATEST",
+	"PRICE_ASC",
+	"PRICE_DESC",
+	"REVIEW_COUNT",
+	"RATING_DESC",
+	"RECOMMEND"
+]).describe("스토어프론트 상품 기본 정렬. `MANUAL`(직접 정한 순서)·`LATEST`(최신순)·`PRICE_ASC`·`PRICE_DESC`·`REVIEW_COUNT`·`RATING_DESC`·`RECOMMEND`(추천순)");
+/** 노출 상태 — 노출 여부와 기간에서 나온 값이다. 숨김이 기간보다 앞선다 */
+const collectionStateSchema = z.enum([
+	"ACTIVE",
+	"SCHEDULED",
+	"ENDED",
+	"HIDDEN"
+]);
+/** 노출 상태 판정 — 숨김 → 시작 전(예약) → 종료 → 노출 중. `now`는 판정 시각이다 */
+function collectionStateOf(collection, now) {
+	if (!collection.visible) return "HIDDEN";
+	const at = now.getTime();
+	if (collection.startsAt && Date.parse(collection.startsAt) > at) return "SCHEDULED";
+	if (collection.endsAt && Date.parse(collection.endsAt) <= at) return "ENDED";
+	return "ACTIVE";
+}
+const collectionSchema = z.object({
+	collectionId: z.string(),
+	type: z.string().describe("유형. 현재 값은 `MANUAL`·`AUTOMATIC`이고 값이 늘 수 있어 문자열이다"),
+	title: z.string(),
+	slug: z.string().describe("스토어프론트 주소에 쓰는 값. 상점 안에서 유일하다"),
+	description: z.string(),
+	imageUrl: z.string().nullable().describe("대표 이미지 주소"),
+	productSort: z.string().describe("스토어프론트 상품 기본 정렬"),
+	visible: z.boolean().describe("노출 여부. false면 기간과 무관하게 스토어프론트에 보이지 않는다"),
+	startsAt: z.string().nullable().describe("노출 시작 시각. null이면 바로 노출한다"),
+	endsAt: z.string().nullable().describe("노출 종료 시각. null이면 끝나지 않는다"),
+	sortOrder: z.number().int().describe("스토어프론트 컬렉션 목록 순서(작을수록 앞)"),
+	metaTitle: z.string().nullable(),
+	metaDescription: z.string().nullable(),
+	state: collectionStateSchema.describe("지금 노출 상태"),
+	productCount: z.number().int().describe("담긴 상품 수(판매 상태 무관)"),
+	revision: z.number().int().describe("수정 번호. 쓰기마다 1씩 오른다. 수정 본문에 주면 그 사이 다른 수정이 있을 때 409다"),
+	createdAt: z.string(),
+	updatedAt: z.string()
+});
+const timeField = (description) => z.iso.datetime({ offset: true }).nullable().optional().describe(description);
+const slugField = z.string().regex(COLLECTION_SLUG_PATTERN).describe("주소. 영문 소문자·숫자·하이픈 64자까지, 상점 안에서 유일하다(겹치면 409 `COLLECTION_SLUG_TAKEN`)");
+const productIdsField = z.array(z.string().min(1)).max(MAX_COLLECTION_PRODUCTS).describe("상품 id. 배열 순서가 직접 정한 순서다. 겹치는 id는 처음 것만 남긴다");
+const commonFields = {
+	description: z.string().max(500).describe("설명(텍스트)"),
+	imageUrl: productImageUrlSchema.nullable().describe("대표 이미지 주소. https만 받는다"),
+	productSort: collectionProductSortRequestSchema,
+	visible: z.boolean().describe("노출 여부"),
+	startsAt: timeField("노출 시작 시각(ISO 8601, 시간대 포함). null이면 바로 노출한다"),
+	endsAt: timeField("노출 종료 시각(ISO 8601, 시간대 포함). null이면 끝나지 않는다"),
+	sortOrder: z.number().int().min(0).max(1e6).describe("목록 순서(작을수록 앞)"),
+	metaTitle: z.string().trim().max(60).nullable().describe("검색 결과 제목"),
+	metaDescription: z.string().trim().max(160).nullable().describe("검색 결과 설명")
+};
+const periodRefine = (body, ctx) => {
+	if (body.startsAt && body.endsAt && Date.parse(body.endsAt) <= Date.parse(body.startsAt)) ctx.addIssue({
+		code: "custom",
+		path: ["endsAt"],
+		message: "종료 시각은 시작 시각보다 뒤여야 합니다"
+	});
+};
+/**
+* `POST /v1/collections` — 직접 선택 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
+* `productIds`는 처음 담을 상품과 순서다.
+*/
+const collectionCreateRequestSchema = z.object({
+	title: z.string().trim().min(1).max(60).describe("제목"),
+	slug: slugField.optional(),
+	type: z.enum(["MANUAL"]).default("MANUAL").describe("유형. 지금은 `MANUAL`(직접 선택)만 받는다. 만든 뒤 바꿀 수 없다"),
+	description: commonFields.description.default(""),
+	imageUrl: commonFields.imageUrl.optional(),
+	productSort: commonFields.productSort.default("MANUAL"),
+	visible: commonFields.visible.default(true),
+	startsAt: commonFields.startsAt,
+	endsAt: commonFields.endsAt,
+	sortOrder: commonFields.sortOrder.optional().describe("목록 순서. 생략하면 맨 뒤"),
+	metaTitle: commonFields.metaTitle.optional(),
+	metaDescription: commonFields.metaDescription.optional(),
+	productIds: productIdsField.optional()
+}).superRefine(periodRefine);
+/**
+* `PATCH /v1/collections/{collectionId}` — 준 항목만 바뀐다. `type`을 주면 400 `COLLECTION_TYPE_IMMUTABLE`이다.
+* `revision`을 주면 그 번호일 때만 바뀌고, 그 사이 다른 수정이 있었으면 409 `COLLECTION_CHANGED`다.
+*/
+const collectionPatchRequestSchema = z.object({
+	title: z.string().trim().min(1).max(60).optional(),
+	slug: slugField.optional(),
+	type: z.string().optional().describe("바꿀 수 없다. 주면 400 `COLLECTION_TYPE_IMMUTABLE`"),
+	description: commonFields.description.optional(),
+	imageUrl: commonFields.imageUrl.optional(),
+	productSort: commonFields.productSort.optional(),
+	visible: commonFields.visible.optional(),
+	startsAt: commonFields.startsAt,
+	endsAt: commonFields.endsAt,
+	sortOrder: commonFields.sortOrder.optional(),
+	metaTitle: commonFields.metaTitle.optional(),
+	metaDescription: commonFields.metaDescription.optional(),
+	revision: z.number().int().min(0).optional().describe("읽은 수정 번호")
+}).superRefine(periodRefine);
+/** `PUT /v1/collections/{collectionId}/products` — 담긴 상품을 통째로 바꾼다(순서 포함) */
+const collectionProductsReplaceRequestSchema = z.object({
+	productIds: productIdsField,
+	revision: z.number().int().min(0).optional().describe("읽은 수정 번호")
+});
+/** `POST /v1/collections/{collectionId}/products` — 뒤에 붙인다. 이미 담긴 상품은 그 자리에 둔다 */
+const collectionProductsAddRequestSchema = z.object({ productIds: z.array(z.string().min(1)).min(1).max(500) });
+/** 컬렉션에 담긴 상품 한 줄 */
+const collectionProductSchema = z.object({
+	productId: z.string(),
+	name: z.string(),
+	thumbnailUrl: z.string().nullable(),
+	status: z.string().describe("판매 상태. 스토어프론트에는 `SALE`만 보인다"),
+	salePrice: z.number().int(),
+	position: z.number().int().describe("직접 정한 순서(1부터)"),
+	addedAt: z.string()
+});
+const collectionStateCountsSchema = z.object({
+	ALL: z.number().int(),
+	ACTIVE: z.number().int(),
+	SCHEDULED: z.number().int(),
+	ENDED: z.number().int(),
+	HIDDEN: z.number().int()
+});
+/** 목록 응답 — 페이지 + 상태별 건수(`q`·`type`·`productId`를 적용하고 `state`는 적용하기 전) */
+const collectionPageSchema = pageSchema(collectionSchema).extend({ stateCounts: collectionStateCountsSchema });
+/** `GET /v1/collections` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const collectionListQuerySchema = z.object({
+	q: z.string().optional().describe("제목·주소 검색(포함, 대소문자 무시)"),
+	type: z.enum(COLLECTION_TYPES).optional().describe("유형"),
+	state: collectionStateSchema.optional().describe("노출 상태"),
+	productId: z.string().optional().describe("이 상품이 담긴 직접 선택 컬렉션만"),
+	...pageQueryShape({
+		defaultSize: 20,
+		maxSize: 200
+	})
+});
+/** `GET /v1/collections/{collectionId}/products` 쿼리 */
+const collectionProductListQuerySchema = z.object({ ...pageQueryShape({
+	defaultSize: 100,
+	maxSize: MAX_COLLECTION_PRODUCTS
+}) });
+//#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",
+	"LINE_AMBIGUOUS",
+	"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`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, `LINE_AMBIGUOUS`=지정한 `optionId`의 줄이 여럿이라 줄을 정할 수 없음(`lineId`로 지목한다), `NO_DISCOUNT`=할인할 금액이 없음");
+/** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
+const MIN_PAYMENT_AMOUNT = 100;
 /**
-* 상품 유형 (이슈 #48·#57) — 배송이 필요한 상품과 필요 없는 상품을 가르는 축이다.
-*
-* **상품 유형은 이행 방식 하나로 표현한다.** `fulfillment.type`이 배송 필요 여부, 이행 흐름, 클레임 규칙을 정한다.
-* 코드 곳곳에서 유형 이름으로 분기하지 않고 이 파일의 판정 함수(`requiresShipping`·`fulfillmentRuleOf`)를 지난다.
+* 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
 *
-* 주문상품 상태 enum은 바꾸지 않는다. 비실물의 **제공 완료는 `DELIVERED`를 재사용한다** — 새 상태를 더하면 기존 소비자의
-* 상태 분기(배송완료 뒤 구매확정 대기, 반품 가능 판정)가 새 값을 모른다. 표시는 유형으로 가른다.
+* 곱셈을 먼저 하고 나눈다. `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));
+}
 /**
-* 상품 유형.
-* - `SHIPPING` 배송 상품. 택배로 발송하고 송장·배송 추적으로 배송완료가 된다
-* - `MANUAL` 배송 없는 상품(비실물). 셀러가 제공 처리(`POST /v1/order-items/{orderItemId}/fulfill`)로 제공 완료를 기록한다
+* 금액을 가중치 비율로 나눈다 — **누적 내림의 차분**이다.
 *
-* 비실물의 세부 구분(파일 다운로드·코드 발급·이용권·방문 수령)은 2026-09-28에 제품에서 뺐다(이슈 #48 범위 축소).
-* 이름은 이행 방식이다 — `SHIPPING`이 택배 발송이듯 `MANUAL`은 셀러가 직접 제공한다는 뜻이다.
+* `i`번째 몫 = `floor(total × W_i / W) − floor(total × W_{i−1} / W)`(`W_i`는 앞에서부터 누적 가중치).
+* 합이 `total`과 정확히 같고, 입력 순서가 같으면 결과도 같다. `total ≤ W`이면 몫이 가중치를 넘지 않는다.
+* 곱이 2^53을 넘을 수 있어 BigInt로 계산한다.
 */
-const fulfillmentTypeSchema = z.enum(["SHIPPING", "MANUAL"]);
+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);
+}
 /**
-* 응답 스키마용 유형 — 서버가 나중에 유형을 더해도 옛 SDK가 응답 파싱에서 깨지지 않게 문자열로 받는다.
-* 요청은 `fulfillmentTypeSchema`(닫힌 enum)로 검증한다.
+* 사용 기간 판정 — 쿠폰 기간과 발급 쿠폰 유효 기간 중 좁은 쪽. 시작은 포함, 종료는 제외.
+* 읽지 못하는 시각은 제한 없음이 아니라 거절이다(fail-closed).
 */
-const fulfillmentTypeResponseSchema = z.string().describe("상품 유형. 현재 값은 `SHIPPING`(배송 상품)·`MANUAL`(배송 없는 상품, 셀러가 제공 처리)이고 값이 추가될 수 있어 문자열로 받는다");
-/** 유형별 규칙표 — **유일한 원천이다.** */
-const FULFILLMENT_RULES = {
-	SHIPPING: {
-		requiresShipping: true,
-		requiresCollection: true,
-		exchangeSupported: true
-	},
-	MANUAL: {
-		requiresShipping: false,
-		requiresCollection: false,
-		exchangeSupported: false
-	}
-};
+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;
+}
 /**
-* 저장된 값 → 유형. null·모르는 값은 `SHIPPING`이다 — 이 필드 이전의 상품·주문상품은 모두 배송 상품이었다.
+* 쿠폰 금액 계산 — **순수 함수다.** DB를 읽지 않는다. 규칙 스냅샷을 만드는 조회와 한도·보유 판정
+* (발급 쿠폰 상태, 1인 한도)은 호출부 몫이다.
+*
+* 종류별로 상품 쿠폰 → 주문 쿠폰 → 배송비 쿠폰 순으로 적용한다. 같은 종류의 자리와 같은 쿠폰 id는
+* **적용된** 쿠폰만 차지한다 — 앞선 주문 쿠폰이 최소 금액 미달이면 뒤의 주문 쿠폰이 쓰이고, 같은 쿠폰의 발급
+* 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
 */
-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;
+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
+	};
 }
-/**
-* 배송이 없는 주문상품의 배송 묶음 키 (`order_items.delivery_bundle_key`).
-*
-* null로 두면 환불 정산이 #29 이전 주문의 레거시 폴백(「묶음 = 같은 상품」, 상품의 **현재** 배송비)을 탄다.
-* 이 키를 만나면 배송비 환불·차감이 0이고 `orders.delivery_fee_settlements`에 항목을 만들지 않는다.
-* 정책 지문 키(`b:…`)와 겹치지 않는다.
-*/
-const NO_SHIPPING_BUNDLE_KEY = "none";
-/** 배송비 유형 — 무료·유료·조건부 무료 */
-const deliveryTypeSchema = z.enum([
-	"FREE",
-	"PAID",
-	"CONDITIONAL_FREE"
-]);
-const KNOWN_FULFILLMENT_TYPES = fulfillmentTypeSchema.options;
-const ADDRESS_ID_DESCRIPTIONS = {
-	shipping: "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 등록에서 생략하면 그 시점 상점 기본 출고지를 저장한다. `null`이면 비워 둔다(상점 기본 출고지를 따른다). 이 상점의 `SHIPPING` 주소가 아니면 거부한다",
-	return: "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 등록에서 생략하면 그 시점 상점 기본 반품지를 저장한다. `null`이면 비워 둔다(상점 기본 반품지를 따른다). 이 상점의 `RETURN` 주소가 아니면 거부한다"
+const NO_COUPON_SETTLEMENT = {
+	chargeAmount: 0,
+	refundAmount: 0,
+	entries: []
 };
 /**
-* 배송비 필드 사이의 일관성 — FREE의 배송비, 조건부 무료가 아닌 상품의 무료 기준을 조용히 0·null로 바꿔 저장하지 않고 400으로 돌려준다
-* (셀러가 저장됐다고 믿는 값이 사라지지 않게). 조건부 무료는 기준 금액이 필수다 — 기준 없는 조건부 무료는 계산상 유료 배송이다.
+* 쿠폰 조건 미달 차감 — **순수 함수다.** 부분 취소·반품으로 남은 주문상품이 쿠폰 조건을 잃으면,
+* 남은 주문상품이 받던 할인만큼을 이번 환불에서 뺀다.
+*
+* 쿠폰마다
+* - `allocatedRemaining` = 남은 수량에 배분된 할인(`proratedRefundBase`로 수량 비율)
+* - `recomputed` = 주문 시점 규칙 스냅샷과 주문 시점 대상 줄로, 남은 금액만 넣어 `quotePricing`을 다시 돌린 할인
+* - 쿠폰이 **여전히 적용되면 목표 0**, 조건을 잃었으면 목표 = `allocatedRemaining`이다. 적용되는 쿠폰의
+*   정률 10원 내림 차이까지 차감하면 조건을 지킨 구매자가 몇 원씩 잃는다 — 조건을 잃은 경우만 본다.
+*   재계산 할인이 더 커지는 경우(정률 최대 할인액)도 차감하지 않고 더 돌려주지도 않는다.
+* - `delta` = 목표 − (이미 차감 + 이미 면제). 양수면 청구하고(판매자 귀책·정책 꺼짐이면 면제로 기록),
+*   음수면 앞서 뺀 차감부터 돌려준다. 마지막 활성 수량까지 취소되면 목표가 0이라 누적 차감이 모두 되돌아가고,
+*   전량 취소의 환불 합계가 결제액과 같아진다.
+* - 청구는 이번 환불에서 실제로 뺄 수 있는 금액(`chargeableAmount` + 이번에 되돌린 금액)을 넘지 않고,
+*   **실제로 뺀 금액만** 기록한다. 못 뺀 나머지는 기록하지 않아 다음 환불이 다시 본다.
+*
+* 배송비 쿠폰은 여기서 다루지 않는다. 배송비 쿠폰을 발급하게 되면(3단계) 묶음 배송비 환불
+* (`computeDeliveryFeeSettlement`)이 그 묶음의 `couponDiscount`를 빼야 한다 — 빼지 않으면 받지 않은 배송비를 돌려준다.
 */
-function refineShippingConsistency(value, ctx) {
-	if (value.deliveryType === "FREE" && value.deliveryFee !== void 0 && value.deliveryFee !== 0) ctx.addIssue({
-		code: "custom",
-		path: ["deliveryFee"],
-		message: "무료 배송(FREE)의 배송비는 0이거나 생략해야 합니다"
-	});
-	const threshold = value.conditionalFreeAmount;
-	const hasThreshold = threshold !== void 0 && threshold !== null;
-	if (value.deliveryType === "CONDITIONAL_FREE" && !hasThreshold) ctx.addIssue({
-		code: "custom",
-		path: ["conditionalFreeAmount"],
-		message: "조건부 무료(CONDITIONAL_FREE)는 무료 기준 금액이 필요합니다"
+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
 	});
-	if (value.deliveryType !== "CONDITIONAL_FREE" && hasThreshold) ctx.addIssue({
-		code: "custom",
-		path: ["conditionalFreeAmount"],
-		message: "무료 기준 금액은 조건부 무료(CONDITIONAL_FREE)에서만 받습니다"
+	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 deliveryTypeDescription = "배송비 유형. `FREE` 무료, `PAID` 유료, `CONDITIONAL_FREE` 조건부 무료";
-const shippingCreateSchema = z.strictObject({
-	deliveryType: deliveryTypeSchema.default("PAID").describe(deliveryTypeDescription),
-	deliveryFee: z.number().int().min(0).optional().describe("배송비. 원 단위. 생략하면 상점 기본 배송비(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 저장한다. FREE면 0이거나 생략한다"),
-	conditionalFreeAmount: z.number().int().min(0).nullable().optional().describe("무료 배송이 되는 묶음 소계. 원 단위. CONDITIONAL_FREE에서만 받고 필수다"),
-	shippingAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
-	returnAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.return)
-}).superRefine(refineShippingConsistency);
-/**
-* 상품 이행 — 등록(POST). 배송 상품의 `shipping`을 생략하면 기본값(유료 배송·상점 기본 배송비·기본 출고지·반품지)이다.
-*/
-const productFulfillmentCreateSchema = z.discriminatedUnion("type", [z.strictObject({
-	type: z.literal("SHIPPING"),
-	shipping: shippingCreateSchema.optional()
-}), z.strictObject({ type: z.literal("MANUAL") })]);
-const shippingUpdateSchema = z.strictObject({
-	deliveryType: deliveryTypeSchema.describe(deliveryTypeDescription),
-	deliveryFee: z.number().int().min(0).describe("배송비. 원 단위. FREE면 0"),
-	conditionalFreeAmount: z.number().int().min(0).nullable().describe("무료 배송이 되는 묶음 소계. CONDITIONAL_FREE면 필수, 아니면 null"),
-	shippingAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
-	returnAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.return)
-}).superRefine(refineShippingConsistency);
-/**
-* 상품 이행 — 수정(PUT·PATCH). 통째 교체이고 유형 키와 그 안의 필드가 **모두 필수**다. 서버는 현재 값과 병합하지 않는다.
-* `fulfillment` 자체를 생략하면 이행을 바꾸지 않는다.
-*/
-const productFulfillmentUpdateSchema = z.discriminatedUnion("type", [z.strictObject({
-	type: z.literal("SHIPPING"),
-	shipping: shippingUpdateSchema
-}), z.strictObject({ type: z.literal("MANUAL") })]);
-/**
-* 저장된 상품 이행 — 알려진 유형의 닫힌 유니온. 서버의 상품 엔티티와 응답이 이 모양을 쓴다.
-* 응답 파싱은 `productFulfillmentResponseSchema`(열린 유니온)를 쓴다.
-*/
-const productFulfillmentSchema = z.discriminatedUnion("type", [z.object({
-	type: z.literal("SHIPPING"),
-	shipping: z.object({
-		deliveryType: deliveryTypeSchema,
-		deliveryFee: z.number().int().describe("배송비. 원 단위. FREE면 0"),
-		conditionalFreeAmount: z.number().int().nullable().describe("조건부 무료 기준 묶음 소계. CONDITIONAL_FREE가 아니면 null"),
-		shippingAddressId: z.string().nullable().describe("출고지 주소 id. null이면 상점 기본 출고지를 따른다"),
-		returnAddressId: z.string().nullable().describe("반품지 주소 id. null이면 상점 기본 반품지를 따른다")
-	})
-}), z.object({ type: z.literal("MANUAL") })]);
-/**
-* 열린 응답 유니온 — 알려진 유형은 판별 유니온으로 검사하고, **모르는 유형만** `{ type: "OTHER", rawType }`로 읽는다.
-*
-* `type: z.string()` 가지를 그대로 두면 TS가 `type === "SHIPPING"`으로 좁혀도 문자열 가지가 남는다. `OTHER` 리터럴로 바꿔 좁히기를
-* 지킨다. 알려진 유형의 모양이 틀린 응답은 폴백으로 숨기지 않고 파싱 오류로 둔다.
-*/
-function openFulfillmentUnion(known) {
-	return z.union([known, z.looseObject({ type: z.string().refine((type) => !KNOWN_FULFILLMENT_TYPES.includes(type), { message: "알려진 유형은 해당 유형의 모양이어야 합니다" }) }).transform((value) => ({
-		type: "OTHER",
-		rawType: value.type
-	}))]);
-}
-const productFulfillmentResponseSchema = openFulfillmentUnion(productFulfillmentSchema).describe("상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 값이 추가될 수 있어 SDK는 모르는 유형을 `{ type: \"OTHER\", rawType }`로 읽는다");
-/**
-* 주문상품의 주문 시점 이행 — 결제 확정이 주문서 줄에서 굳힌다. 상품의 현재 값이 아니다. 서버는 주문상품 컬럼
-* (`fulfillment_type`·`delivery_bundle_key`)과 jsonb(`fulfillment_snapshot`)를 합쳐 이 모양을 만든다.
-*/
-const orderItemFulfillmentSnapshotSchema = z.discriminatedUnion("type", [z.object({
-	type: z.literal("SHIPPING"),
-	shipping: z.object({
-		bundleKey: z.string().nullable().describe("배송 묶음 키. 같은 키의 주문상품이 배송비를 한 번 낸 한 묶음이다. #29 이전 주문은 null"),
-		returnAddressId: z.string().nullable().describe("주문 시점 반품지 주소 id. null이거나 지워진 주소면 상점 기본 반품지로 안내한다")
-	})
-}), z.object({ type: z.literal("MANUAL") })]);
-const orderItemFulfillmentSnapshotResponseSchema = openFulfillmentUnion(orderItemFulfillmentSnapshotSchema).describe("주문 시점 이행 스냅샷. 상품을 나중에 고쳐도 바뀌지 않는다. 제공 기록은 `fulfillment`에 있다. 값이 추가될 수 있어 SDK는 모르는 유형을 `OTHER`로 읽는다");
-//#endregion
-//#region src/schemas/payment.ts
+	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
+	};
+}
 /**
-* 상점 결제(PG) 설정과 매출 리포트 계약.
+* 주문상품의 실결제 금액 중 이번 취소 수량의 몫 — **실결제 금액(`totalPrice − couponDiscountAmount`)을
+* 누적 내림의 차분으로 나눈다.**
 *
-* PG는 셀러가 직접 계약한다. 자격 증명은 상점별로 저장되고, 비밀 값(시크릿 키·API Secret·
-* 웹훅 시크릿)은 저장 후 다시 조회할 수 없다. 응답에는 앞 4자리 마스킹만 나온다. 공개 값
-* (클라이언트 키·Store ID·채널 키)은 원래 브라우저 결제창에 노출되는 값이라 그대로 돌려준다.
-*/
-const pgProviderSchema = z.enum(["tosspayments", "portone"]).describe("PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2)");
-const pgPaymentMethodSchema = z.enum([
-	"CARD",
-	"BANK_TRANSFER",
-	"VIRTUAL_ACCOUNT",
-	"MOBILE",
-	"EASY_PAY"
-]).describe("결제수단 (스토어프론트 결제 요청의 `paymentMethod`와 같은 값)");
-/**
-* 간편결제사 — 결제 옵션(스토어프론트 `paymentOptions`)과 PG 설정의 `easyPayProviders`에 쓴다.
-* `@sayren/storefront-sdk`의 `easyPayProviderSchema`와 같은 값이다(api 계약 테스트가 고정한다)
-*/
-const easyPayProviderSchema = z.enum([
-	"NAVERPAY",
-	"KAKAOPAY",
-	"TOSSPAY",
-	"PAYCO"
-]);
-/**
-* 응답에 실리는 간편결제사 — 서버가 간편결제사를 추가해도 파싱이 깨지지 않게 문자열로 받는다
-* (`pgProvider`·결제수단과 같은 방식). 요청(`easyPayProviders`)은 값을 골라 보내는 자리라 enum 그대로다.
-* 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 화면은 모르는 값을 원문 그대로 보여 준다.
+* 상품 금액과 쿠폰 배분을 따로 나눠 빼면 합은 같지만 한 번의 몫이 −1원이 되는 경우가 있다
+* (예: 금액 3원·할인 2원·수량 5개에서 셋째 개). 음수를 0으로 자르면 합이 1원 넘친다. 실결제 금액을
+* 바로 나누면 몫이 항상 0 이상이고 전량 취소의 합이 실결제 금액과 정확히 같다.
 */
-const easyPayProviderResponseSchema = z.string();
-const pgEnvironmentSchema = z.enum(["TEST", "LIVE"]).describe("PG 결제 환경. `TEST`=PG 샌드박스(테스트 키, 실제로 돈이 오가지 않음), `LIVE`=실결제(운영 키)");
-const pgVerificationResultSchema = z.enum(["SUCCESS", "FAILED"]).describe("연결 테스트 결과");
-/** 비밀 값 입력 — 저장 후 다시 조회할 수 없다 */
-const secretInput = () => z.string().trim().min(8).max(512);
+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 개별 연동(`*_ck_`·`*_sk_`)만 쓴다. 위젯 키는 결제창 SDK가
-* `NOT_SUPPORTED_WIDGET_KEY`로, 서버 API가 404 `NOT_FOUND_MERCHANT`로 거부하므로 저장 전에 막는다.
-* 요청 스키마·api 어댑터·상점 플랫폼 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
+* 쿠폰 관리 API 계약 (이슈 #47) — `/v1/coupons/**`, 스코프 `promotion:r|rw`.
+*
+* 금액 계산 규칙은 `promotion.ts`(`quotePricing`)가 원천이고, 여기에는 셀러가 쿠폰을 만들고 나눠 주는 표면만 있다.
+* 발급·사용이 시작된 쿠폰은 혜택·조건·대상·사용 시작일을 바꿀 수 없다(409 `COUPON_LOCKED`). 이름·설명·종료일 연장·
+* 한도 상향·중지·재개·종료만 된다. 규칙을 바꾸려면 새 쿠폰을 만든다.
 */
-const TOSS_WIDGET_CLIENT_KEY_PATTERN = /^(test|live)_gck_/;
-/** 토스페이먼츠 결제위젯 시크릿 키 접두사. {@link TOSS_WIDGET_CLIENT_KEY_PATTERN} 참고 */
-const TOSS_WIDGET_SECRET_KEY_PATTERN = /^(test|live)_gsk_/;
-/** 결제위젯 키를 거부할 때의 필드 메시지 */
-const TOSS_WIDGET_KEY_MESSAGE = "결제위젯 키가 아니라 API 개별 연동 키를 입력해주십시오";
-const tossPaymentsCredentialsInputSchema = z.object({
-	clientKey: z.string().trim().min(8).max(200).describe("클라이언트 키 (`test_ck_…`/`live_ck_…`). 공개 값 — 결제창에서 쓰인다"),
-	secretKey: secretInput().optional().describe("시크릿 키 (`test_sk_…`/`live_sk_…`). 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
-	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 보안 키. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
-}).superRefine((value, ctx) => {
-	if (TOSS_WIDGET_CLIENT_KEY_PATTERN.test(value.clientKey)) ctx.addIssue({
-		code: "custom",
-		path: ["clientKey"],
-		message: TOSS_WIDGET_KEY_MESSAGE
-	});
-	if (value.secretKey !== void 0 && TOSS_WIDGET_SECRET_KEY_PATTERN.test(value.secretKey)) ctx.addIssue({
+/** 쿠폰 상태 — `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: ["secretKey"],
-		message: TOSS_WIDGET_KEY_MESSAGE
+		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", "종료 시각은 시작 시각보다 뒤여야 합니다");
 });
-/** 포트원 채널 목록 최소 개수. 결제수단을 받으려면 채널이 하나는 있어야 한다 */
-const PORTONE_MIN_CHANNELS = 1;
-/** 포트원 채널 목록 최대 개수 */
-const PORTONE_MAX_CHANNELS = 20;
-/** 포트원 채널 표시 이름 최대 길이 */
-const PORTONE_CHANNEL_NAME_MAX_LENGTH = 50;
-const portOneChannelSchema = z.object({
-	channelKey: z.string().trim().min(8).max(200).describe("포트원 콘솔 [연동 정보] > [채널 관리]의 채널 키. 공개 값"),
-	name: z.string().trim().max(50).nullable().optional().describe("채널 표시 이름 (예: 카드 전용)"),
-	payMethods: z.array(pgPaymentMethodSchema).min(1).max(pgPaymentMethodSchema.options.length).describe("이 채널로 받을 결제수단. 결제수단마다 먼저 나열된 채널이 쓰인다")
+/**
+* `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 portOneCredentialsInputSchema = z.object({
-	storeId: z.string().trim().min(8).max(200).describe("포트원 Store ID (`store-…`). 공개 값"),
-	channels: z.array(portOneChannelSchema).min(1).max(20).describe("채널 목록. 포트원 V2는 PG·결제수단별로 채널을 따로 추가하므로 여러 개를 등록할 수 있다"),
-	apiSecret: secretInput().optional().describe("V2 API Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
-	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 시크릿. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
+/** 쿠폰 응답 */
+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()
 });
-const upsertEnvironment = () => pgEnvironmentSchema.describe("저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. 어느 세트로 결제할지는 이 값이 아니라 샌드박스 스위치(`sandboxMode`)가 정한다");
-const upsertTossPaymentsProviderRequestSchema = z.object({
-	environment: upsertEnvironment(),
-	credentials: tossPaymentsCredentialsInputSchema
+/** `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 upsertPortOneProviderRequestSchema = z.object({
-	environment: upsertEnvironment(),
-	credentials: portOneCredentialsInputSchema
+const couponRedemptionListQuerySchema = z.object({
+	status: z.enum([
+		"RESERVED",
+		"USED",
+		"RELEASED",
+		"RESTORED"
+	]).optional(),
+	...pageQueryShape()
 });
-const updatePaymentProviderRequestSchema = z.object({
-	enabled: z.boolean().optional().describe("사용 여부. 켜려면 활성 환경(샌드박스면 TEST, 아니면 LIVE) 자격 증명이 모두 저장돼 있어야 한다(`PAYMENT_PROVIDER_INCOMPLETE`)"),
-	sandboxMode: z.boolean().optional().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(항상 허용). `false`(라이브 전환)는 라이브 개방 조건을 모두 충족해야 한다(`LIVE_GATE_NOT_MET`)"),
-	easyPayProviders: z.array(easyPayProviderSchema).max(easyPayProviderSchema.options.length).optional().describe("이 PG로 받는 간편결제사 — 통째로 바꾼다. PG 계약(포트원은 채널)에 추가한 간편결제만 켠다. 켠 간편결제사마다 스토어프론트 결제 옵션이 하나씩 생긴다(포트원은 간편결제를 받는 채널이 있어야 한다)")
-}).refine((body) => body.enabled !== void 0 || body.sandboxMode !== void 0 || body.easyPayProviders !== void 0, { message: "enabled·sandboxMode·easyPayProviders 중 하나는 보내야 합니다" });
-const verifyPaymentProviderRequestSchema = z.object({ environment: pgEnvironmentSchema.optional().describe("연결 테스트할 자격 증명 세트. 생략하면 활성 환경(샌드박스면 TEST, 아니면 LIVE)") });
-const updatePaymentSettingsRequestSchema = z.object({
-	priority: z.array(pgProviderSchema).min(1).max(50).optional().describe("PG 우선순위(앞이 1순위) — 스토어프론트 결제 옵션 목록의 PG 순서다. 연결된 PG 수만큼 **모두 한 번씩** 나열한다(길이 상한 50은 안전장치다). 빠지거나 중복되거나 연결되지 않은 PG가 있으면 `INVALID_PRIORITY`"),
-	checkoutOrigins: z.array(z.string().max(200)).max(20).optional().describe("결제 도메인 — 통째로 바꾼다. 결제를 마친 구매자가 돌아올 스토어프론트 origin(`https://shop.example.com`, https·경로 없음). 결제 시작의 `returnUrl`은 이 목록 안이어야 한다. 비어 있으면 실결제를 시작할 수 없다(테스트 결제는 localhost 허용). 같은 도메인을 PG 가맹 정보에도 등록한다. 형식이 틀리면 `INVALID_CHECKOUT_ORIGIN`")
-}).refine((body) => body.priority !== void 0 || body.checkoutOrigins !== void 0, { message: "priority 또는 checkoutOrigins 중 하나는 보내야 합니다" });
-const maskedSecretSchema = z.object({
-	field: z.string().describe("비밀 필드 이름 (`secretKey`·`apiSecret`·`webhookSecret`)"),
-	configured: z.boolean().describe("값이 저장돼 있는가"),
-	masked: z.string().nullable().describe("앞 4자리만 남긴 마스킹 값 (예: `test****`). 저장되지 않았으면 null")
+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`) 주문의 결제 금액 합계 (원). 부분 취소·반품 환불은 빼지 않은 결제 시점 금액이다")
 });
-const publicConfigSchema = z.union([z.object({ clientKey: z.string() }), z.object({
-	storeId: z.string(),
-	channels: z.array(portOneChannelSchema)
-})]);
-const verificationSchema = z.object({
-	result: pgVerificationResultSchema,
-	message: z.string().nullable(),
-	checkedAt: z.string()
+/** `GET /v1/customers/{customerId}/coupons` 항목 — 발급 쿠폰 + 쿠폰 이름·혜택 */
+const customerCouponSchema = couponIssueSchema.extend({
+	couponName: z.string(),
+	kind: couponKindSchema,
+	benefit: couponBenefitSchema
 });
-const paymentCredentialSetSchema = z.object({
-	environment: pgEnvironmentSchema,
-	publicConfig: publicConfigSchema.describe("공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`"),
-	secrets: z.array(maskedSecretSchema).describe("비밀 값의 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
-	lastVerification: verificationSchema.nullable().describe("이 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
-	updatedAt: z.string()
+//#endregion
+//#region src/schemas/customer.ts
+/** 구매자 목록 정렬 */
+const customerSortSchema = z.enum([
+	"joined_desc",
+	"joined_asc",
+	"total_paid_desc",
+	"order_count_desc",
+	"last_ordered_desc"
+]).describe("정렬. `joined_desc`(기본, 최근 가입순)·`joined_asc`·`total_paid_desc`(구매 금액순)·`order_count_desc`(주문 수순)·`last_ordered_desc`(최근 주문순)");
+/** `GET /v1/customers` 쿼리 */
+const customerListQuerySchema = z.object({
+	q: z.string().optional().describe("검색어 — 이름·이메일(포함). 숫자 4자리면 휴대폰 뒤 4자리로도 찾는다"),
+	joinedFrom: z.string().optional().describe("가입일 시작(YYYY-MM-DD, KST, 포함)"),
+	joinedTo: z.string().optional().describe("가입일 끝(YYYY-MM-DD, KST, 포함)"),
+	marketing: z.enum(["agreed", "declined"]).optional().describe("마케팅 수신 동의 필터. 생략하면 전체"),
+	sort: customerSortSchema.optional(),
+	...pageQueryShape()
 });
-const liveGateConditionCodeSchema = z.enum([
-	"TEST_CONNECTION",
-	"SANDBOX_PAYMENT",
-	"SANDBOX_REFUND",
-	"LIVE_CONNECTION",
-	"PLATFORM_LIVE_ENABLED"
-]).describe("라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, `SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, `PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠");
-const liveGateConditionSchema = z.object({
-	code: liveGateConditionCodeSchema,
-	met: z.boolean().describe("충족 여부"),
-	message: z.string().describe("조건 설명 또는 미충족 사유")
+/** 구매 통계 — 구매 금액은 취소된 주문 상품을 빼고, 완료된 반품은 수량 비율로 뺀 금액이다 */
+const customerStatsSchema = z.object({
+	orderCount: z.number().int().describe("주문 수(취소 포함)"),
+	totalPaid: z.number().int().describe("구매 금액(원) — 취소·완료된 반품 제외"),
+	lastOrderedAt: z.string().nullable().describe("최근 주문 시각")
 });
-const liveGateSchema = z.object({
-	status: z.enum(["LOCKED", "OPEN"]).describe("`OPEN`=조건을 모두 충족해 샌드박스를 끌 수 있다, `LOCKED`=아직 끌 수 없다"),
-	conditions: z.array(liveGateConditionSchema),
-	openedAt: z.string().nullable().describe("마지막으로 라이브로 전환한 시각. 없으면 null")
+/** 목록 행 — 휴대폰은 가운데를 가린다(`010-****-1234`) */
+const customerSummarySchema = z.object({
+	customerId: z.string(),
+	name: z.string(),
+	/** 소셜 가입에서 이메일을 받지 못했으면 null */
+	email: z.string().nullable(),
+	maskedPhone: z.string().nullable(),
+	joinedAt: z.string(),
+	point: z.number().int(),
+	marketingAgreed: z.boolean()
+}).extend(customerStatsSchema.shape);
+const customerAddressSchema = z.object({
+	addressId: z.string(),
+	alias: z.string(),
+	isDefault: z.boolean(),
+	receiverName: z.string(),
+	phone: z.string(),
+	zipCode: z.string(),
+	address1: z.string(),
+	address2: z.string().nullable()
 });
+/** 동의 종류 — 이용약관·개인정보 수집이용은 가입 필수, 마케팅 수신은 선택 */
+const consentKindSchema = z.enum([
+	"TERMS",
+	"PRIVACY",
+	"MARKETING"
+]);
+const consentActionSchema = z.enum(["AGREED", "WITHDRAWN"]);
 /**
-* 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의 `ApiError.details` 형태.
-* 응답 파싱용이라 관대하다 — 알 수 없는 키는 버리고, 형태가 다르면 safeParse 실패로 처리한다.
+* 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
+* `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
+* `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
 */
-const liveGateErrorDetailsSchema = z.object({ conditions: z.array(liveGateConditionSchema).describe("라이브 개방 조건별 충족 여부 (순서 고정)") });
-const paymentProviderSchema = z.object({
-	provider: pgProviderSchema,
-	displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
-	connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
-	enabled: z.boolean().describe("결제에 사용 중인가"),
-	priority: z.number().int().nullable().describe("우선순위 (1이 가장 높다). 연결되지 않았으면 null"),
-	environment: pgEnvironmentSchema.nullable().describe("새 결제에 쓰는 환경(활성 환경). 샌드박스 스위치가 켜져 있으면 `TEST`, 꺼져 있으면 `LIVE`. 연결되지 않았으면 null"),
-	publicConfig: publicConfigSchema.nullable().describe("활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`. 활성 세트가 없으면 null"),
-	secrets: z.array(maskedSecretSchema).describe("활성 환경 세트의 비밀 값 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
-	lastVerification: verificationSchema.nullable().describe("활성 환경 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+const consentSourceSchema = z.enum([
+	"SIGNUP",
+	"SOCIAL_SIGNUP",
+	"DELEGATED",
+	"RECONSENT",
+	"MEMBER_UPDATE",
+	"SELLER"
+]);
+/** 동의 이력 한 줄 — 추가만 되고 지워지지 않는다(구매자 탈퇴 시에만 함께 지워진다) */
+const customerConsentSchema = z.object({
+	consentId: z.string(),
+	kind: consentKindSchema,
+	/** 동의한 약관 버전. 마케팅은 버전이 없어 null */
+	version: z.string().nullable(),
+	/** 동의 시점의 약관 문서 주소. 상점이 주소를 정하지 않았거나 마케팅이면 null */
+	documentUrl: z.string().nullable(),
+	action: consentActionSchema,
+	source: consentSourceSchema,
+	occurredAt: z.string()
+});
+/** 종류별 현재 동의 상태 */
+const customerConsentStateSchema = z.object({
+	kind: consentKindSchema,
+	agreed: z.boolean(),
+	/** 동의한 약관 버전. 마케팅이거나 이력이 없으면 null */
+	agreedVersion: z.string().nullable(),
+	/** 상점의 현재 약관 버전. 마케팅은 null */
+	currentVersion: z.string().nullable(),
+	/** 상점이 정한 현재 약관 문서 주소. 정하지 않았거나 마케팅이면 null */
+	currentDocumentUrl: z.string().nullable(),
 	updatedAt: z.string().nullable(),
-	sandboxMode: z.boolean().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(실제로 돈이 오가지 않는다). 연결되지 않았으면 true"),
-	credentialSets: z.object({
-		TEST: paymentCredentialSetSchema.nullable(),
-		LIVE: paymentCredentialSetSchema.nullable()
-	}).describe("환경별 자격 증명 세트. 등록되지 않은 세트는 null"),
-	liveGate: liveGateSchema.describe("라이브 개방 조건. 조건을 모두 충족해야 샌드박스를 끌 수 있다"),
-	easyPayProviders: z.array(easyPayProviderResponseSchema).describe("이 PG로 받는 간편결제사. 연결되지 않았으면 빈 목록. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
-	retiredCredentialCount: z.number().int().describe("보관된(가맹점 교체·연결 해제로 새 결제에 더 쓰이지 않는) 자격 증명 수. 그 가맹점으로 받은 결제의 환불·대사에 계속 쓰인다"),
-	routingExclusion: z.string().nullable().optional().default(null).describe("지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(상점 플랫폼이 다시 계산하지 않는다). 후보가 아닌 PG에는 항상 사유 코드를 붙인다(연결 안 된 PG 포함) — 모든 PG는 `candidates`에 있거나 이 값이 null이 아니다. 현재 값: `NOT_CONNECTED`(연결 안 됨) · `DISABLED`(사용 중지) · `CREDENTIAL_MISSING`(활성 환경 자격 증명 없음) · `SANDBOX_IN_LIVE_STORE`(다른 PG가 라이브라 이 샌드박스 PG는 실구매자 결제에 쓰지 않음) · `PLATFORM_BLOCKED`(플랫폼이 실결제를 막음) · `MODE_MISMATCH`(라이브를 연 서버 모드와 현재 모드가 다름). 값이 추가될 수 있어 문자열로 받는다 — 모르는 값은 후보 아님으로 다룬다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다")
+	/** 약관이 개정돼 다시 받아야 하는가. 마케팅은 항상 false */
+	reconsentRequired: z.boolean()
 });
-/**
-* `PaymentProvider.routingExclusion`의 현재 값 — 응답 스키마는 서버가 사유를 추가해도 파싱이 깨지지 않게 문자열로 받는다.
-* 화면 문구 분기는 이 목록으로 하고, 모르는 값은 "후보 아님"으로 다룬다.
-*/
-const PAYMENT_ROUTING_EXCLUSION_CODES = [
-	"NOT_CONNECTED",
-	"DISABLED",
-	"CREDENTIAL_MISSING",
-	"SANDBOX_IN_LIVE_STORE",
-	"PLATFORM_BLOCKED",
-	"MODE_MISMATCH"
-];
-/**
-* 결제수단 반복 실패 경고(#86 후속) — 같은 PG·결제수단(·간편결제사)이 가맹점 설정 문제(구매자가 고칠 수 없는 실패, 예: KG이니시스
-* `V105 [NO MPI SET] 전용화면 미설정`)로 기간 안에 여러 번 실패했다. 구매자에게는 「이 결제수단은 지금 사용할 수 없습니다」가 보이고,
-* PG 관리자에서 그 결제수단의 전용 화면·채널을 설정해야 다시 쓸 수 있다
-*/
-const paymentFailureWarningSchema = z.object({
-	provider: z.string().describe("PG(`tosspayments`·`portone`). 값이 추가될 수 있어 문자열로 받는다"),
-	method: z.string().describe("결제수단(`CARD`·`BANK_TRANSFER`·`VIRTUAL_ACCOUNT`·`MOBILE`·`EASY_PAY`)"),
-	easyPayProvider: easyPayProviderResponseSchema.nullable().describe("간편결제사. 간편결제가 아니면 null"),
-	code: z.string().nullable().describe("PG 실패 코드(예: `V105`, `AllChannelsNotSatisfied`). PG 원문 문구로만 판정했으면 null"),
-	count: z.number().int().describe("기간 안의 실패 횟수"),
-	lastAt: z.string().describe("마지막 실패 시각"),
-	message: z.string().nullable().describe("마지막 실패의 PG 원문 사유. 구매자에게는 보이지 않는다")
+const customerConsentsSchema = z.object({
+	terms: customerConsentStateSchema,
+	privacy: customerConsentStateSchema,
+	marketing: customerConsentStateSchema,
+	/** 필수 동의 중 하나라도 현재 버전이 아니면 true */
+	reconsentRequired: z.boolean()
+});
+/** `GET /v1/customers/{id}/consents` 쿼리 — 최근 순이다 */
+const customerConsentListQuerySchema = z.object({
+	kind: consentKindSchema.optional().describe("동의 종류 필터. 생략하면 전체"),
+	...pageQueryShape()
+});
+/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
+const customerDetailSchema = z.object({
+	customerId: z.string(),
+	name: z.string(),
+	email: z.string().nullable(),
+	phone: z.string().nullable(),
+	joinedAt: z.string(),
+	point: z.number().int(),
+	marketingAgreed: z.boolean(),
+	loginMethods: z.array(z.object({
+		method: z.enum([
+			"password",
+			"kakao",
+			"naver",
+			"google"
+		]),
+		/** 소셜 연결 시각. 비밀번호는 가입 시각 */
+		linkedAt: z.string()
+	})).describe("로그인 방법 — 이메일·비밀번호(`password`)와 연결된 소셜 계정"),
+	consents: customerConsentsSchema.describe("약관·개인정보·마케팅 동의의 현재 상태. 이력은 `GET /v1/customers/{customerId}/consents`"),
+	addresses: z.array(customerAddressSchema),
+	stats: customerStatsSchema.extend({
+		canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),
+		reviewCount: z.number().int(),
+		inquiryCount: z.number().int().describe("상품 문의 + 1:1 문의")
+	})
+});
+/** 구매자의 주문 — 전체 기간 */
+const customerOrderSchema = z.object({
+	orderId: z.string(),
+	orderedAt: z.string(),
+	totalAmount: z.number().int().describe("결제 금액"),
+	testPayment: z.boolean(),
+	items: z.array(z.object({
+		orderItemId: z.string(),
+		productName: z.string(),
+		optionName: z.string().nullable(),
+		quantity: z.number().int(),
+		status: orderItemStatusSchema,
+		claimStatus: z.enum([
+			"CANCEL_REQUESTED",
+			"RETURN_REQUESTED",
+			"EXCHANGE_REQUESTED"
+		]).nullable()
+	}))
 });
-const paymentSettingsSchema = z.object({
-	checkoutOrigins: z.array(z.string()).describe("결제 도메인 — 결제를 마친 구매자가 돌아올 스토어프론트 origin 목록"),
-	providers: z.array(paymentProviderSchema).describe("지원하는 모든 PG. 연결된 것은 우선순위순, 연결되지 않은 것은 뒤에 온다"),
-	environment: pgEnvironmentSchema.nullable().optional().default(null).describe("지금 결제를 시작하면 쓰는 결제 환경. 사용 가능한 PG 중 하나라도 라이브면 `LIVE`(샌드박스 PG는 제외), 아니면 `TEST`. 사용 가능한 PG가 없으면 null. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다"),
-	candidates: z.array(z.string()).optional().default(() => []).describe("지금 결제를 시작하면 쓰는 PG, 우선순위순(`tosspayments`·`portone`). 비어 있으면 구매자가 결제할 수 없다. 빠진 PG의 사유는 `providers[].routingExclusion` — 후보가 아닌 PG에는 항상 사유 코드를 붙인다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다"),
-	warnings: z.array(paymentFailureWarningSchema).optional().default(() => []).describe("최근 24시간 안에 같은 PG·결제수단·간편결제사가 가맹점 설정 문제로 3번 이상 실패한 조합, 마지막 실패가 최근인 순. 판정 규칙은 서버가 정하고 바뀔 수 있다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다")
+/** `POST /v1/customers/{id}/withdraw` 본문 */
+const withdrawCustomerRequestSchema = z.object({
+	reason: z.enum([
+		"BUYER_REQUEST",
+		"DORMANT",
+		"ABUSE",
+		"OTHER"
+	]).describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
+	memo: z.string().max(200).optional().describe("사유 보충(선택)")
 });
-const paymentProviderVerificationSchema = z.object({
-	provider: pgProviderSchema,
-	environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
-	result: pgVerificationResultSchema,
-	message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
-	checkedAt: z.string()
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
+const customerWithdrawalBlockedDetailsSchema = z.object({
+	inProgressOrderItems: z.number().int(),
+	openClaims: z.number().int(),
+	pendingPayments: z.number().int()
 });
-const salesReportGroupBySchema = z.enum([
-	"DAY",
-	"PROVIDER",
-	"METHOD",
-	"PROVIDER_METHOD"
-]).describe("행 집계 기준. 기본 `DAY`");
-const reportDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
-const salesReportQuerySchema = z.object({
-	from: reportDate.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
-	to: reportDate.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
-	provider: pgProviderSchema.optional().describe("PG 필터"),
-	method: pgPaymentMethodSchema.optional().describe("결제수단 필터 — **실제 결제수단**(PG가 보고한 수단, 모르면 요청 수단) 기준. 결제창에서 결제수단이 바뀔 수 있다(카드 결제창의 간편결제 탭 등). 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다"),
-	groupBy: salesReportGroupBySchema.optional(),
-	includeTest: z.enum(["true", "false"]).optional().describe("테스트 결제(샌드박스 결제) 포함 여부. 기본 `false` — 테스트 결제의 승인·환불은 집계에서 빠진다")
+//#endregion
+//#region src/schemas/login.ts
+/** 소셜 로그인 공급자 */
+const loginProviderSchema = z.enum([
+	"kakao",
+	"naver",
+	"google"
+]);
+/** 공급자 연결 상태 — 비밀 값은 앞 4자리만 */
+const loginProviderStatusSchema = z.object({
+	provider: loginProviderSchema,
+	connected: z.boolean(),
+	/** 스토어프론트에서 사용 중인지. 연결 안 됐으면 false */
+	enabled: z.boolean(),
+	clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
+	secretPrefix: z.string().nullable(),
+	lastTestedAt: z.string().nullable(),
+	lastTestOk: z.boolean().nullable(),
+	linkedMemberCount: z.number().int().describe("이 공급자로 연결된 구매자 수"),
+	/** 이 공급자로만 로그인하는 구매자 수 — 연결을 해제하면 로그인할 방법이 없어진다 */
+	onlyMethodMemberCount: z.number().int(),
+	callbackUrl: z.url().describe("공급자 개발자 콘솔에 등록할 리디렉트 URI")
 });
-const salesTotalsSchema = z.object({
-	paymentCount: z.number().int().describe("승인 건수"),
-	paymentAmount: z.number().int().describe("승인 금액 합계"),
-	refundCount: z.number().int().describe("환불(취소) 건수. 부분 취소도 1건"),
-	refundAmount: z.number().int().describe("환불 금액 합계"),
-	netAmount: z.number().int().describe("순매출 = 승인 금액 - 환불 금액"),
-	pgFeeAmount: z.number().int().nullable().describe("PG 수수료 (참고용). PG에서 확정 값을 받지 못하면 null")
+/** `GET /v1/store/login-settings` */
+const loginSettingsSchema = z.object({
+	passwordLoginEnabled: z.boolean(),
+	/** 비밀번호로만 로그인하는 구매자 수 — 이메일·비밀번호를 끄면 이들은 로그인할 수 없다 */
+	passwordOnlyMemberCount: z.number().int(),
+	storefrontOrigins: z.array(z.string()),
+	providers: z.array(loginProviderStatusSchema)
 });
-const salesReportRowSchema = salesTotalsSchema.extend({
-	date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
-	provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
-	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단(PG가 보고한 수단, 모르면 요청 수단). groupBy에 METHOD가 포함될 때만 값. 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다")
+/** `PATCH /v1/store/login-settings` */
+const updateLoginSettingsRequestSchema = z.object({ passwordLoginEnabled: z.boolean() });
+/** `PUT /v1/store/auth-providers/{provider}` — 저장 전에 연결 테스트를 한다 */
+const saveLoginProviderRequestSchema = z.object({
+	clientId: z.string().trim().min(1).max(200),
+	clientSecret: z.string().trim().min(1).max(500)
 });
-const salesReportSchema = z.object({
-	from: z.string(),
-	to: z.string(),
-	timezone: z.literal("Asia/Seoul"),
-	currency: z.literal("KRW"),
-	groupBy: salesReportGroupBySchema,
-	provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
-	method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
-	includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
-	summary: salesTotalsSchema.describe("기간 전체 합계"),
-	rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다")
+/** `PATCH /v1/store/auth-providers/{provider}` */
+const updateLoginProviderRequestSchema = z.object({ enabled: z.boolean() });
+/** 연결 테스트 결과 */
+const loginProviderTestSchema = z.object({
+	ok: z.boolean(),
+	/** 실패 이유 — `INVALID_CLIENT`(키가 틀림)·`PROVIDER_UNAVAILABLE`(공급자 응답 없음) */
+	code: z.enum(["INVALID_CLIENT", "PROVIDER_UNAVAILABLE"]).nullable(),
+	testedAt: z.string()
 });
-/**
-* 결제 내역 — 결제 건(세션) 단위 공개 상태. 주문 단위 상태와 다르다.
-* - `APPROVED`: 승인됐고 환불이 없다
-* - `PARTIALLY_REFUNDED`·`REFUNDED`: 승인 뒤 일부·전액을 환불했다
-* - `PENDING`: 승인 결과를 아직 확정하지 못했다(대사 잡이 확정한다)
-* - `FAILED`: 승인되지 않고 끝났다(거절·준비 장애·구매자 취소·만료)
-*/
-const paymentRecordStatusSchema = z.enum([
-	"APPROVED",
-	"PARTIALLY_REFUNDED",
-	"REFUNDED",
-	"PENDING",
-	"FAILED"
+//#endregion
+//#region src/schemas/misc.ts
+const inquirySchema = z.object({
+	inquiryId: z.string(),
+	productId: z.string(),
+	productName: z.string(),
+	orderItemId: z.string().nullable(),
+	category: z.enum([
+		"PRODUCT",
+		"DELIVERY",
+		"RETURN",
+		"EXCHANGE",
+		"ETC"
+	]),
+	content: z.string(),
+	secret: z.boolean(),
+	writerMaskedName: z.string(),
+	answered: z.boolean(),
+	answer: z.object({
+		content: z.string(),
+		answeredAt: z.string(),
+		modifiedCount: z.number().int().max(1)
+	}).nullable(),
+	createdAt: z.string()
+});
+const customerInquiryCategorySchema = z.enum([
+	"DELIVERY",
+	"RETURN",
+	"EXCHANGE",
+	"PAYMENT",
+	"ETC"
 ]);
-const paymentAttemptStatusSchema = z.string().describe("시도 상태 — ready·approving·approved·unknown·declined·prepare_failed·canceled·failed·abandoned·voided. 새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다");
-/**
-* 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
-* - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
-* - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
-* - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
-* - `CANCELED`: 전액 환불로 취소됐다
-* - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
-* - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
-*/
-const CASH_RECEIPT_STATUS_VALUES = [
-	"REQUESTED",
-	"PENDING",
-	"ISSUED",
-	"CANCELED",
-	"FAILED",
-	"SKIPPED"
-];
-const cashReceiptSchema = z.object({
-	cashReceiptId: z.string(),
-	status: z.string().describe("상태. `REQUESTED` 결제 전 · `PENDING` 발급 대기 · `ISSUED` 발급 · `CANCELED` 취소 · `FAILED` 실패 · `SKIPPED` 발급 대상 아님. 값이 추가될 수 있다"),
-	type: z.string().describe("용도. `INCOME_DEDUCTION` 소득공제 · `EXPENSE_PROOF` 지출증빙"),
-	identityType: z.string().describe("식별 번호 종류. `PHONE` 휴대폰 · `CARD` 현금영수증카드 · `BUSINESS` 사업자등록번호"),
-	identityNumberMasked: z.string().describe("가린 식별 번호 (예: 010****5678). 원문은 조회할 수 없다"),
-	amount: z.number().int().describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
-	issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
-	provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
-	issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
-	receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
-	issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
-	canceledAt: z.string().nullable().describe("최근 취소 시각 (ISO 8601)"),
-	failCode: z.string().nullable().describe("마지막 실패 코드. 성공하면 비운다"),
-	failMessage: z.string().nullable().describe("마지막 실패 사유"),
-	reissuable: z.boolean().describe("상점 플랫폼 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
-	requestedAt: z.string().describe("신청 시각 (ISO 8601)"),
-	updatedAt: z.string().describe("마지막 변경 시각 (ISO 8601)")
+/** 셀러 뷰 1:1 문의 — 작성자 마스킹명 + 답변 수정횟수 포함 */
+const sellerCustomerInquirySchema = z.object({
+	inquiryId: z.string(),
+	memberMaskedName: z.string(),
+	category: customerInquiryCategorySchema,
+	title: z.string(),
+	content: z.string(),
+	orderItemId: z.string().nullable(),
+	answered: z.boolean(),
+	answer: z.object({
+		content: z.string(),
+		answeredAt: z.string(),
+		modifiedCount: z.number().int().max(1)
+	}).nullable(),
+	createdAt: z.string()
 });
-const paymentRecordSchema = z.object({
-	paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
-	orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
-	orderName: z.string().describe("주문명 (예: 무선 이어폰 프로 외 1건)"),
-	customerName: z.string().describe("구매자명"),
-	status: paymentRecordStatusSchema,
-	amount: z.number().int().describe("결제 금액"),
-	refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
-	provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
-	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
-	easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("간편결제사. `method`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 요청한 간편결제사다. 그 밖의 결제수단과 간편결제 이전 결제는 null. 서버는 항상 싣는다. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
-	environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
-	testPayment: z.boolean().describe("샌드박스 결제인가"),
-	pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
-	attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
-	attemptCount: z.number().int().describe("시도 횟수"),
-	failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
-	failMessage: z.string().nullable().describe("실패 사유"),
-	paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
-	createdAt: z.string().describe("결제 시작 시각 (ISO 8601)"),
-	cashReceiptStatus: z.string().nullable().optional().default(null).describe("현금영수증 상태(`cashReceiptSchema.status`와 같은 값). 신청이 없으면 null. 서버는 항상 싣는다")
+const answeredQuery = z.enum(["true", "false"]).optional().describe("답변 여부 필터. `true`면 답변된 문의만, `false`면 미답변만, 생략하면 전부");
+/** `GET /v1/inquiries` 쿼리(상품 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+const inquiryListQuerySchema = z.object({
+	answered: answeredQuery,
+	productId: z.string().optional().describe("상품 id 필터"),
+	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+	...pageQueryShape()
+});
+/** `GET /v1/customer-inquiries` 쿼리(1:1 문의) — OpenAPI 문서용 형태(값은 쿼리 문자열). 최신순이다 */
+const customerInquiryListQuerySchema = z.object({
+	answered: answeredQuery,
+	category: customerInquiryCategorySchema.optional().describe("문의 유형 필터"),
+	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+	...pageQueryShape()
+});
+const settlementStatusSchema = z.enum([
+	"SCHEDULED",
+	"PAID",
+	"HELD"
+]);
+const settlementSummarySchema = z.object({
+	settlementId: z.string(),
+	settlementDate: z.string(),
+	payoutDate: z.string().nullable(),
+	status: settlementStatusSchema,
+	totalPaymentAmount: z.number().int(),
+	totalCommission: z.number().int(),
+	totalDeliveryFee: z.number().int(),
+	adjustmentAmount: z.number().int(),
+	settlementAmount: z.number().int(),
+	itemCount: z.number().int()
 });
-const paymentRecordPageSchema = pageSchema(paymentRecordSchema);
-const paymentAttemptRecordSchema = z.object({
-	attemptId: z.string(),
-	sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
-	provider: pgProviderSchema,
-	status: paymentAttemptStatusSchema,
-	method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
-	easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("주문서에서 고른 간편결제사. 간편결제가 아니면 null. 서버는 항상 싣는다(값이 추가될 수 있어 문자열)"),
-	approvedMethod: pgPaymentMethodSchema.nullable().describe("PG가 보고한 실제 결제수단"),
-	approvedEasyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("PG가 보고한 실제 간편결제사. 모르거나 간편결제가 아니면 null. 서버는 항상 싣는다(값이 추가될 수 있어 문자열)"),
-	amount: z.number().int(),
-	environment: pgEnvironmentSchema,
-	pgTransactionId: z.string().nullable(),
-	failCode: z.string().nullable(),
-	failMessage: z.string().nullable(),
-	createdAt: z.string(),
-	updatedAt: z.string()
+const settlementDetailSchema = z.object({
+	orderItemId: z.string(),
+	productName: z.string(),
+	settlementType: z.enum([
+		"SALE",
+		"REFUND_DEDUCTION",
+		"ADJUSTMENT"
+	]),
+	paymentAmount: z.number().int(),
+	salesCommission: z.number().int(),
+	paymentCommission: z.number().int(),
+	commissionRate: z.number(),
+	deliveryFee: z.number().int(),
+	settlementAmount: z.number().int(),
+	purchaseDecidedAt: z.string().nullable()
 });
-const paymentRefundRecordSchema = z.object({
-	refundId: z.string(),
-	amount: z.number().int(),
-	reason: z.string().describe("환불 사유 코드"),
-	kind: z.string().describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
-	status: z.string().describe("SUCCEEDED·FAILED"),
-	failMessage: z.string().nullable(),
-	requestedAt: z.string(),
-	completedAt: z.string().nullable()
+/** `GET /v1/settlements/{settlementId}` 응답 — 정산 요약 + 상세 내역(`size`건까지) */
+const settlementWithDetailsSchema = settlementSummarySchema.extend({ details: z.array(settlementDetailSchema).optional() });
+/** `GET /v1/settlements` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 정산일 최신순이다 */
+const settlementListQuerySchema = z.object({
+	from: z.string().describe("정산일 조회 시작 (ISO 8601, 포함). 필수"),
+	to: z.string().optional().describe("정산일 조회 끝 (ISO 8601, 포함). 생략하면 from부터 31일. 기간은 최대 31일"),
+	status: settlementStatusSchema.optional().describe("정산 상태 필터"),
+	...pageQueryShape()
 });
-const paymentRecordDetailSchema = paymentRecordSchema.extend({
-	refundableAmount: z.number().int().describe("환불 가능 잔액 = 승인 금액 - 환불 완료 금액"),
-	merchantId: z.string().nullable().describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
-	attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
-	refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다"),
-	cashReceipt: cashReceiptSchema.nullable().optional().default(null).describe("현금영수증. 구매자가 신청하지 않았으면 null. 서버는 항상 싣는다")
+/** `GET /v1/settlements/{settlementId}` 쿼리 — `size`는 돌려줄 상세 내역 건수다(`page`는 무시) */
+const settlementDetailQuerySchema = z.object(pageQueryShape({
+	defaultSize: 100,
+	maxSize: 300
+}));
+const eventTypeSchema = z.enum([
+	"ORDER.PAID",
+	"ORDER.CONFIRMED",
+	"ORDER.DISPATCHED",
+	"ORDER.DELIVERED",
+	"ORDER.PURCHASE_DECIDED",
+	"ORDER.ADDRESS_CHANGE_REQUESTED",
+	"ORDER.CANCELED",
+	"ORDER.FULFILLED",
+	"CLAIM.CANCEL_REQUESTED",
+	"CLAIM.RETURN_REQUESTED",
+	"CLAIM.EXCHANGE_REQUESTED",
+	"CLAIM.COMPLETED",
+	"INQUIRY.CREATED",
+	"REVIEW.CREATED",
+	"PRODUCT.OUT_OF_STOCK"
+]).describe("웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)");
+const webhookStatusSchema = z.enum(["ACTIVE", "SUSPENDED"]).describe("구독 상태. `ACTIVE`=발송 대상, `SUSPENDED`=24시간 이상 연속 전송 실패로 발송이 정지된 상태. 정지 중 발생한 이벤트는 적재하지 않는다. 재개(`POST /webhooks/{id}/resume`)하거나 구독을 수정하면 ACTIVE로 돌아간다");
+const webhookSchema = z.object({
+	webhookId: z.string(),
+	url: z.url(),
+	eventTypes: z.array(eventTypeSchema),
+	status: webhookStatusSchema,
+	secretPrefix: z.string().describe("서명 시크릿 앞부분(식별용, 서명 검증에 사용할 수 없음). 예: `whsec_1a2b`"),
+	suspendedAt: z.string().nullable().describe("발송이 정지된 일시 (ISO 8601). `ACTIVE`면 null"),
+	createdAt: z.string()
 });
-/** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
-const paymentListQuerySchema = z.object({
-	from: z.string().optional().describe("조회 시작 시각 (ISO 8601, 포함). 생략하면 최근 30일"),
-	to: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 기간은 최대 92일"),
-	status: z.string().optional().describe("결제 상태 필터 (PaymentRecordStatus)"),
-	provider: z.string().optional().describe("PG 필터"),
-	method: z.string().optional().describe("실제 결제수단 필터"),
-	keyword: z.string().optional().describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
-	includeTest: z.string().optional().describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
-	page: z.string().optional().describe("페이지 번호 (1부터)"),
-	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
+/** 등록 응답 — 서명 시크릿 평문은 이 응답에서만 노출된다 */
+const webhookCreatedSchema = webhookSchema.extend({ secret: z.string().describe("서명 시크릿 평문. 등록 응답에서만 노출되며 다시 조회할 수 없다") });
+/** 시크릿 교체 응답 */
+const webhookSecretRotatedSchema = z.object({
+	secret: z.string().describe("새 서명 시크릿 평문. 이 응답에서만 노출된다"),
+	oldSecretExpiresAt: z.string().describe("기존 시크릿의 병행 유효 종료 일시 (ISO 8601). 이때까지는 기존 시크릿 서명도 함께 붙는다")
 });
-//#endregion
-//#region src/schemas/upload.ts
-/**
-* 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
-*
-* - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
-* - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
-*/
-const uploadPurposeSchema = z.enum(["product-image", "description"]);
-const MB = 1048576;
-/**
-* 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
-*
-* 크기는 **요청이 스스로 신고한 값**으로만 검사한다. 바이트는 api를 거치지 않고 CDN으로
-* 직접 PUT되므로 이 검사는 셀러가 올리기 전에 알게 하는 장치이고, 실제 상한은 CDN이 강제한다.
-*/
-const UPLOAD_PURPOSE_LIMITS = {
-	"product-image": {
-		extensions: [
-			"jpg",
-			"jpeg",
-			"png",
-			"webp",
-			"avif",
-			"gif"
-		],
-		maxBytes: 10 * MB
-	},
-	description: {
-		extensions: [
-			"jpg",
-			"jpeg",
-			"png",
-			"gif",
-			"webp",
-			"avif",
-			"svg",
-			"mp4",
-			"webm",
-			"mov"
-		],
-		maxBytes: 50 * MB
-	}
-};
-/** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
-function uploadExtensionOf(filename) {
-	const dot = filename.lastIndexOf(".");
-	if (dot < 0 || dot === filename.length - 1) return "";
-	return filename.slice(dot + 1).toLowerCase();
-}
+const webhookDeliveryStatusSchema = z.enum([
+	"PENDING",
+	"PENDING_RETRY",
+	"SUCCESS",
+	"FAILED"
+]).describe("전송 상태. `PENDING`=첫 시도 전, `PENDING_RETRY`=실패 후 재시도 대기, `SUCCESS`=2xx 응답 수신, `FAILED`=재시도를 모두 소진했거나 구독 정지로 종료");
+const webhookDeliveryErrorCodeSchema = z.enum([
+	"TIMEOUT",
+	"CONNECTION_FAILED",
+	"BLOCKED_ADDRESS",
+	"NON_2XX",
+	"WEBHOOK_SUSPENDED"
+]).describe("전송 실패 사유. `TIMEOUT`=10초 안에 응답 없음, `CONNECTION_FAILED`=연결 실패(DNS·TLS 포함), `BLOCKED_ADDRESS`=사설·루프백 등 전송이 허용되지 않는 주소, `NON_2XX`=2xx가 아닌 응답(리다이렉트 포함), `WEBHOOK_SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨");
 /**
-* 용도 제한 위반 여부. 통과하면 `null`.
-* 서버가 던지는 오류와 상점 플랫폼이 먼저 띄우는 안내가 갈리지 않도록 한 함수로 판정한다.
+* 실패 원인 분류의 **현재** 값. 응답 스키마(`webhookFailureReasonSchema`)는 문자열로 열려 있다 —
+* 서버가 값을 더해도 이전 SDK가 목록 파싱에 실패하지 않게 한다(택배 추적 `stage`와 같은 이유).
+* 모르는 값은 `errorCode`로 판단한다.
 */
-function uploadRejection(purpose, filename, size) {
-	const limit = UPLOAD_PURPOSE_LIMITS[purpose];
-	if (!limit.extensions.includes(uploadExtensionOf(filename))) return {
-		status: 400,
-		code: "UNSUPPORTED_FILE_TYPE",
-		message: `지원하지 않는 파일 형식입니다. ${limit.extensions.join(", ")}만 올릴 수 있습니다`
-	};
-	if (size !== void 0 && size > limit.maxBytes) return {
-		status: 413,
-		code: "FILE_TOO_LARGE",
-		message: `파일이 너무 큽니다. ${Math.floor(limit.maxBytes / MB)}MB까지 올릴 수 있습니다`
-	};
-	return null;
-}
+const WEBHOOK_FAILURE_REASONS = [
+	"DNS",
+	"TLS",
+	"TIMEOUT",
+	"CONNECTION",
+	"HTTP_4XX",
+	"HTTP_5XX",
+	"HTTP_OTHER",
+	"SSRF_BLOCKED",
+	"SUSPENDED"
+];
+const webhookFailureReasonSchema = z.string().describe("실패 원인 분류(진단용). 현재 값은 `DNS`=호스트 이름을 주소로 바꾸지 못함, `TLS`=인증서·핸드셰이크 실패, `TIMEOUT`=10초 안에 응답 없음, `CONNECTION`=연결 거부·끊김, `HTTP_4XX`·`HTTP_5XX`=그 대역의 응답, `HTTP_OTHER`=2xx·4xx·5xx가 아닌 응답(리다이렉트 등), `SSRF_BLOCKED`=사설·루프백 등 전송이 허용되지 않는 주소, `SUSPENDED`=구독 정지로 대기 중인 전송이 종료됨. `errorCode`보다 잘게 나눈 값이며 둘은 함께 쓸 수 있다. 값이 추가될 수 있으므로 모르는 값은 `errorCode`로 판단한다");
 /**
-* 미디어 업로드 자리 발급 — `POST /v1/uploads`.
-*
-* 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
-* 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
-* (확장자만 쓰이고 이름 자체는 저장되지 않는다).
+* 대상 리소스 종류의 **현재** 값. 응답 스키마는 문자열로 열려 있다(새 이벤트가 새 리소스를 가리킬 수 있다).
 */
-const uploadRequestSchema = z.object({
-	filename: z.string().min(1).max(255),
-	purpose: uploadPurposeSchema.default("description").describe("업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다"),
-	size: z.number().int().positive().optional().describe("파일 바이트 크기. 주면 용도별 상한을 발급 전에 검사한다")
+const WEBHOOK_RESOURCE_TYPES = [
+	"ORDER",
+	"CLAIM",
+	"PRODUCT",
+	"REVIEW",
+	"INQUIRY"
+];
+const webhookResourceTypeSchema = z.string().describe("이벤트가 가리키는 리소스 종류. 현재 값은 `ORDER`·`CLAIM`·`PRODUCT`·`REVIEW`·`INQUIRY`이고 값이 추가될 수 있다");
+/** 이벤트가 가리키는 대상 리소스 — 전송 기록을 주문·상품과 잇는 키 */
+const webhookDeliveryResourceSchema = z.object({
+	type: webhookResourceTypeSchema,
+	id: z.string().describe("리소스 ID. 전송 기록 조회의 `resourceId`, API 로그 조회의 `q`로 그대로 넣을 수 있다")
+});
+/** 발송 요청 헤더 한 줄 (값 마스킹) */
+const webhookRequestHeaderSchema = z.object({
+	name: z.string().describe("헤더 이름"),
+	value: z.string().nullable().describe("헤더 값. 서명(`Sayren-Signature`)처럼 비밀이 섞이는 헤더는 이름만 주고 값은 null이다")
+});
+/** 웹훅 전송 기록 한 건 (전송 기록 조회 항목) */
+const webhookDeliverySchema = z.object({
+	deliveryId: z.string().describe("전송 기록 ID. 수신 요청의 `Sayren-Delivery-Id` 헤더 값"),
+	eventId: z.string().describe("이벤트 ID. 재시도·재전송해도 같은 이벤트면 같은 값이다. 수신 측 중복 제거 키로 쓴다"),
+	eventType: eventTypeSchema,
+	url: z.string().describe("전송 시점의 대상 URL"),
+	status: webhookDeliveryStatusSchema,
+	responseStatusCode: z.number().int().nullable().describe("마지막 시도의 HTTP 응답 코드. 미시도·연결 실패·타임아웃·차단이면 null"),
+	responseTimeMs: z.number().int().nullable().describe("마지막 시도의 응답 시간(ms). 미시도·연결 실패면 null"),
+	responseBodyExcerpt: z.string().nullable().describe("마지막 시도의 응답 본문 앞부분(최대 4,096자). 응답이 없으면 null. 가린 뒤에 자른다. 키 이름에 `authorization`·`token`·`secret`·`password`·`key`·`signature`·`credential`·`cookie`가 **들어 있으면**(부분 일치, 대소문자 무시. 예: `apiKey`·`access_token`·`keyword`) 그 값을 `***`로 가린다. 값이 객체·배열이면 통째로 가린다. 평문 `Authorization: …` 같은 헤더 줄, `Bearer <토큰>`, 쿼리 형식 `access_token=…`, 끝에서 잘려 닫히지 않은 값도 가린다"),
+	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회. 전송 도중 장애로 결과를 기록하지 못한 시도도 센다"),
+	createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
+	attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
+	nextAttemptAt: z.string().nullable().describe("다음 시도 예정 일시 (ISO 8601). `PENDING`·`PENDING_RETRY`일 때만 값이 있다"),
+	redeliveryOf: z.string().nullable().describe("수동 재전송으로 생긴 기록이면 원본 전송 기록 ID. 아니면 null"),
+	redeliveredAs: z.string().nullable().describe("이 기록을 원본으로 수동 재전송해 생긴 기록의 전송 기록 ID. 아직 재전송하지 않았으면 null. 재전송은 원본당 1회다")
+});
+/** 발송 본문 최대 노출 길이(바이트). 넘으면 잘라 주고 `payloadTruncated`가 true다 */
+const WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES = 16384;
+/** 웹훅 전송 기록 상세 — `GET /webhooks/{id}/deliveries/{deliveryId}`. 목록 항목 + 요청 본문·헤더 */
+const webhookDeliveryDetailSchema = webhookDeliverySchema.extend({
+	payload: z.string().describe(`수신 서버로 보낸 요청 본문 그대로(JSON 문자열). 서명은 이 문자열을 대상으로 계산한다. 최대 ${WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES / 1024}KB까지 주고 넘으면 잘라 준다`),
+	payloadTruncated: z.boolean().describe("본문이 길어서 잘렸으면 true. true면 `payload`는 유효한 JSON이 아니다"),
+	payloadMasked: z.boolean().describe("민감 키 마스킹(`responseBodyExcerpt`와 같은 키 이름 규칙)이 본문을 바꿨으면 true. true면 `payload`는 보낸 본문과 달라 서명을 맞춰 볼 수 없다. 이벤트 본문에는 보통 민감 키가 없어 false다"),
+	requestHeaders: z.array(webhookRequestHeaderSchema).describe("발송 요청에 실은 헤더. 값은 전송 시점 그대로이나 서명 헤더는 이름만 주고 값은 null이다. `Content-Length`는 실제로 보낸 본문(마스킹·자르기 전)의 바이트 수다. 매 시도가 같은 헤더 집합을 쓰고 서명·타임스탬프만 달라진다")
 });
-const uploadTicketSchema = z.object({
-	/** 업로드 완료 후 공개될 주소 */
-	url: z.url(),
-	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
-	uploadUrl: z.url()
+/** 전송 기록 조회 쿼리 — `GET /webhooks/{id}/deliveries` */
+const webhookDeliveryListQuerySchema = z.object({
+	status: webhookDeliveryStatusSchema.optional().describe("전송 상태 필터. 생략하면 전체"),
+	eventType: eventTypeSchema.optional().describe("이벤트 타입 필터. 생략하면 전체"),
+	resourceId: z.string().optional().describe("대상 리소스 ID 필터(정확히 일치). 주문·클레임·상품·리뷰·문의 id를 넣으면 그 리소스의 이벤트만 남는다. 같은 id로 API 로그를 `q`로 검색하면 그 리소스를 건드린 API 요청을 볼 수 있다"),
+	limit: z.coerce.number().int().min(1).max(100).optional().describe("최대 건수 (1~100, 기본 50). 최신 적재순으로 반환하며 보관 기간은 30일이다")
 });
-//#endregion
-//#region src/schemas/product.ts
-const productStatusSchema = z.enum([
-	"SALE",
-	"SUSPENDED",
-	"OUT_OF_STOCK",
-	"CLOSED"
-]);
-const productSummarySchema = z.object({
+/** 실패 건 일괄 재전송 응답 — `POST /webhooks/{id}/deliveries/redeliver-failed` */
+const webhookRedeliverFailedResultSchema = z.object({ queued: z.number().int().min(0).describe("재전송 대기열에 올린 건수. 최근 72시간의 `FAILED` 중 아직 재전송되지 않은 건이 대상이며 최대 500건이다") });
+const webhookTestRequestSchema = z.object({ eventType: eventTypeSchema.describe("샘플 페이로드로 보낼 이벤트 타입") });
+/** 테스트 이벤트 발송 결과 (동기 반환). 재시도·정지 판정·전송 기록이 없다 */
+const webhookTestResultSchema = z.object({
+	responseStatusCode: z.number().int().nullable().describe("수신 서버의 HTTP 응답 코드. 연결 실패·타임아웃·차단이면 null"),
+	responseTimeMs: z.number().int().nullable().describe("응답 시간(ms). 연결 실패면 null"),
+	errorCode: webhookDeliveryErrorCodeSchema.nullable().describe("실패 사유. 2xx 응답이면 null"),
+	failureReason: webhookFailureReasonSchema.nullable().describe("실패 원인 분류. 2xx 응답이면 null"),
+	responseBodyExcerpt: z.string().nullable().describe("응답 본문 앞부분(최대 4,096자). 규칙은 전송 기록의 `responseBodyExcerpt`와 같다. 응답이 없으면 null"),
+	requestHeaders: z.array(webhookRequestHeaderSchema).describe("보낸 요청 헤더. 서명 헤더는 이름만 주고 값은 null이다"),
+	payload: z.string().describe("보낸 요청 본문 그대로(JSON 문자열). 샘플 이벤트다")
+});
+const webhookRequestSchema = z.object({
+	url: z.url().startsWith("https://", "웹훅 URL은 HTTPS만 허용됩니다"),
+	eventTypes: z.array(eventTypeSchema).min(1)
+});
+const reviewSchema = z.object({
+	reviewId: z.string(),
 	productId: z.string(),
-	name: z.string(),
-	status: productStatusSchema,
-	salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
-	discountedPrice: z.number().int().nullable().describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
-	/** usable variant 재고 합계 (서버 계산) */
-	stockQuantity: z.number().int().describe("판매 가능한 옵션 재고의 합계. 서버가 계산한다"),
-	categoryId: z.string().nullable(),
-	thumbnailUrl: z.url().optional(),
-	/** optionGroups.length > 0 */
-	hasOptions: z.boolean(),
-	fulfillment: z.object({ type: fulfillmentTypeResponseSchema }).describe("상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다"),
-	updatedAt: z.string(),
-	sample: z.boolean().optional().default(false).describe("상점을 만들 때 넣은 샘플 상품인가(이슈 #70). 상점 플랫폼이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다")
+	productName: z.string(),
+	orderItemId: z.string(),
+	optionName: z.string().nullable(),
+	rating: z.number().int().min(1).max(5),
+	content: z.string(),
+	images: z.array(z.url()),
+	writerMaskedName: z.string(),
+	blinded: z.boolean(),
+	reply: z.object({
+		content: z.string(),
+		repliedAt: z.string(),
+		updatedAt: z.string().nullable()
+	}).nullable(),
+	createdAt: z.string()
 });
-/** 옵션 축(그룹)이 가지는 값 하나 — 예: 축 "색상"의 값 "블랙" */
-const optionValueSchema = z.object({
-	valueId: z.string(),
-	name: z.string(),
-	sortOrder: z.number().int()
+const reviewSortSchema = z.enum([
+	"createdAt.desc",
+	"createdAt.asc",
+	"rating.asc",
+	"rating.desc"
+]);
+/** `GET /v1/reviews` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const reviewListQuerySchema = z.object({
+	productId: z.string().optional().describe("상품 id 필터"),
+	rating: z.enum([
+		"1",
+		"2",
+		"3",
+		"4",
+		"5"
+	]).optional().describe("별점 필터 (일치)"),
+	replied: z.enum(["true", "false"]).optional().describe("답글 여부 필터. `true`면 답글 단 리뷰만, `false`면 답글 없는 리뷰만"),
+	hasImage: z.enum(["true", "false"]).optional().describe("`true`면 이미지가 있는 리뷰만"),
+	from: z.string().optional().describe("작성 시각 조회 시작 (ISO 8601, 포함)"),
+	sort: reviewSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
+	...pageQueryShape()
 });
-/** 옵션 축(그룹) — 예: "색상", "사이즈" */
-const optionGroupSchema = z.object({
-	groupId: z.string(),
-	name: z.string(),
-	sortOrder: z.number().int(),
-	values: z.array(optionValueSchema)
+/** `POST /v1/reviews/{reviewId}/report` 응답(202) — 신고 접수 */
+const reviewReportResultSchema = z.object({
+	reviewId: z.string(),
+	status: z.literal("PENDING_REVIEW")
 });
+//#endregion
+//#region src/schemas/payment.ts
 /**
-* 판매 단위(SKU). variantId는 기존 optionId 값 공간을 승계하므로
-* 카트·주문·리뷰·클레임의 optionId가 곧 variantId다.
+* 상점 결제(PG) 설정과 매출 리포트 계약.
+*
+* PG는 셀러가 직접 계약한다. 자격 증명은 상점별로 저장되고, 비밀 값(시크릿 키·API Secret·
+* 웹훅 시크릿)은 저장 후 다시 조회할 수 없다. 응답에는 앞 4자리 마스킹만 나온다. 공개 값
+* (클라이언트 키·Store ID·채널 키)은 원래 브라우저 결제창에 노출되는 값이라 그대로 돌려준다.
 */
-const productVariantSchema = z.object({
-	variantId: z.string(),
-	/** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
-	valueIds: z.array(z.string()),
-	/** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
-	name: z.string(),
-	additionalPrice: z.number().int(),
-	stockQuantity: z.number().int(),
-	sku: z.string().nullable(),
-	barcode: z.string().nullable(),
-	costPrice: z.number().int().nullable(),
-	weightGram: z.number().int().nullable(),
-	sellerCode: z.string().nullable(),
-	usable: z.boolean(),
-	hasOrders: z.boolean().optional().describe("주문에 담긴 적이 있는 조합인가(이슈 #59). true인 조합은 옵션 교체에서 뺄 수 없고(409 `OPTION_HAS_ORDERS`) `usable: false`로 판매를 끈다. 서버는 항상 싣는다. 요청에는 쓰지 않는다")
-});
-/** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
-const MAX_OPTION_GROUPS = 3;
-/** 축 하나가 가질 수 있는 값의 최대 개수 */
-const MAX_VALUES_PER_GROUP = 100;
-/** 상품 하나가 가질 수 있는 variant(SKU) 최대 개수 */
-const MAX_VARIANTS = 500;
-/** 추가 선택 옵션명 최대 개수 */
-const MAX_ADDON_GROUPS = 5;
-/** 직접 입력 항목 최대 개수 */
-const MAX_CUSTOM_INPUTS = 5;
-/** 직접 입력 항목 최대 글자 수의 상한 */
-const MAX_CUSTOM_INPUT_LENGTH = 200;
-/** 조합 수가 이 값 이상이면 상점 플랫폼이 경고한다(상한은 `MAX_VARIANTS`) */
-const VARIANT_COUNT_WARNING = 100;
+const pgProviderSchema = z.enum(["tosspayments", "portone"]).describe("PG 식별자. `tosspayments`=토스페이먼츠, `portone`=포트원(V2)");
+const pgPaymentMethodSchema = z.enum([
+	"CARD",
+	"BANK_TRANSFER",
+	"VIRTUAL_ACCOUNT",
+	"MOBILE",
+	"EASY_PAY"
+]).describe("결제수단 (스토어프론트 결제 요청의 `paymentMethod`와 같은 값)");
 /**
-* 옵션 값 정렬 순서 — 등록순·가나다순·낮은 추가금순·높은 추가금순. 서버가 저장할 때 이 순서로 값의 `sortOrder`를 매긴다.
-* 추가금순은 추가 선택 값이면 값의 추가금, 조합 값이면 그 값이 든 조합 추가금의 최솟값으로 비교하고 같으면 등록순이다.
+* 간편결제사 — 결제 옵션(스토어프론트 `paymentOptions`)과 PG 설정의 `easyPayProviders`에 쓴다.
+* `@sayren/storefront-sdk`의 `easyPayProviderSchema`와 같은 값이다(api 계약 테스트가 고정한다)
 */
-const optionSortSchema = z.enum([
-	"REGISTERED",
-	"NAME",
-	"PRICE_ASC",
-	"PRICE_DESC"
+const easyPayProviderSchema = z.enum([
+	"NAVERPAY",
+	"KAKAOPAY",
+	"TOSSPAY",
+	"PAYCO"
 ]);
-/** 추가 선택 값 — 예: 옵션명 "선물 포장"의 값 "포장함"(+2,000원) */
-const addonValueSchema = z.object({
-	valueId: z.string(),
-	name: z.string(),
-	sortOrder: z.number().int(),
-	additionalPrice: z.number().int().describe("이 값을 고르면 단가에 더하는 금액(원, 0 이상)"),
-	usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 고를 수 없다")
-});
-/** 추가 선택 옵션명 */
-const addonGroupSchema = z.object({
-	groupId: z.string(),
-	name: z.string(),
-	sortOrder: z.number().int(),
-	required: z.boolean().describe("구매자가 꼭 골라야 하는가. false면 고르지 않아도 된다"),
-	values: z.array(addonValueSchema)
-});
-/** 직접 입력 항목 — 예: 각인 문구 */
-const customInputSchema = z.object({
-	inputId: z.string(),
-	label: z.string().describe("항목명"),
-	placeholder: z.string().nullable().describe("입력 안내(구매자 입력 칸의 안내 문구). 없으면 null"),
-	maxLength: z.number().int().describe("최대 글자 수"),
-	required: z.boolean(),
-	usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않는다"),
-	sortOrder: z.number().int()
-});
 /**
-* 직접 입력 항목명에 쓸 수 없는 개인정보성 단어 — 상점 플랫폼 검사와 서버 400(`CUSTOM_INPUT_LABEL_FORBIDDEN`)이 이 목록 하나를 쓴다.
-* 구매자 개인정보는 주문 정보로 받는다. 직접 입력 항목으로 받으면 보관·파기 규칙 밖에 남는다.
+* 응답에 실리는 간편결제사 — 서버가 간편결제사를 추가해도 파싱이 깨지지 않게 문자열로 받는다
+* (`pgProvider`·결제수단과 같은 방식). 요청(`easyPayProviders`)은 값을 골라 보내는 자리라 enum 그대로다.
+* 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 화면은 모르는 값을 원문 그대로 보여 준다.
 */
-const CUSTOM_INPUT_FORBIDDEN_WORDS = [
-	"연락처",
-	"전화",
-	"휴대폰",
-	"핸드폰",
-	"폰번호",
-	"메일",
-	"주소",
-	"주민",
-	"생년월일",
-	"생일",
-	"실명",
-	"계좌",
-	"카드번호",
-	"비밀번호",
-	"여권",
-	"통관",
-	"phone",
-	"mobile",
-	"mail",
-	"address"
-];
-/** 금지어 비교용 정규화 — NFKC(전각·호환 문자를 보통 문자로)·소문자 뒤 문자·숫자만 남긴다(공백·기호·제로폭 문자로 쪼갠 우회를 막는다) */
-function forbiddenWordKeyOf(text) {
-	return text.normalize("NFKC").toLowerCase().replace(/[^\p{L}\p{N}]/gu, "");
-}
+const easyPayProviderResponseSchema = z.string();
+const pgEnvironmentSchema = z.enum(["TEST", "LIVE"]).describe("PG 결제 환경. `TEST`=PG 샌드박스(테스트 키, 실제로 돈이 오가지 않음), `LIVE`=실결제(운영 키)");
+const pgVerificationResultSchema = z.enum(["SUCCESS", "FAILED"]).describe("연결 테스트 결과");
+/** 비밀 값 입력 — 저장 후 다시 조회할 수 없다 */
+const secretInput = () => z.string().trim().min(8).max(512);
 /**
-* 직접 입력 항목명·입력 안내에 든 개인정보성 금지어. 없으면 null. 공백·기호·대소문자·전각을 무시한다.
-* 서버는 항목명과 입력 안내 둘 다 이 함수로 검사한다(안내에 「연락처를 적어 주십시오」라고 쓰는 우회를 막는다).
+* 토스페이먼츠 결제위젯 키 접두사. 결제창은 API 개별 연동(`*_ck_`·`*_sk_`)만 쓴다. 위젯 키는 결제창 SDK가
+* `NOT_SUPPORTED_WIDGET_KEY`로, 서버 API가 404 `NOT_FOUND_MERCHANT`로 거부하므로 저장 전에 막는다.
+* 요청 스키마·api 어댑터·상점 플랫폼 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
 */
-function customInputLabelForbiddenWord(label) {
-	const normalized = forbiddenWordKeyOf(label);
-	return CUSTOM_INPUT_FORBIDDEN_WORDS.find((word) => normalized.includes(forbiddenWordKeyOf(word))) ?? null;
-}
-/** 옵션명·값 이름 — 앞뒤 공백을 지우고 빈 값은 받지 않는다 */
-const optionNameSchema = z.string().trim().min(1).max(50);
-const addonValueRequestSchema = z.object({
-	/** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
-	valueId: z.string().optional(),
-	name: optionNameSchema,
-	additionalPrice: z.number().int().min(0).default(0).describe("추가금(원, 0 이상)"),
-	usable: z.boolean().default(true)
+const TOSS_WIDGET_CLIENT_KEY_PATTERN = /^(test|live)_gck_/;
+/** 토스페이먼츠 결제위젯 시크릿 키 접두사. {@link TOSS_WIDGET_CLIENT_KEY_PATTERN} 참고 */
+const TOSS_WIDGET_SECRET_KEY_PATTERN = /^(test|live)_gsk_/;
+/** 결제위젯 키를 거부할 때의 필드 메시지 */
+const TOSS_WIDGET_KEY_MESSAGE = "결제위젯 키가 아니라 API 개별 연동 키를 입력해주십시오";
+const tossPaymentsCredentialsInputSchema = z.object({
+	clientKey: z.string().trim().min(8).max(200).describe("클라이언트 키 (`test_ck_…`/`live_ck_…`). 공개 값 — 결제창에서 쓰인다"),
+	secretKey: secretInput().optional().describe("시크릿 키 (`test_sk_…`/`live_sk_…`). 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 보안 키. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
+}).superRefine((value, ctx) => {
+	if (TOSS_WIDGET_CLIENT_KEY_PATTERN.test(value.clientKey)) ctx.addIssue({
+		code: "custom",
+		path: ["clientKey"],
+		message: TOSS_WIDGET_KEY_MESSAGE
+	});
+	if (value.secretKey !== void 0 && TOSS_WIDGET_SECRET_KEY_PATTERN.test(value.secretKey)) ctx.addIssue({
+		code: "custom",
+		path: ["secretKey"],
+		message: TOSS_WIDGET_KEY_MESSAGE
+	});
 });
-const addonGroupRequestSchema = z.object({
-	/** 전달 시 기존 옵션명 행을 유지(UPDATE). 조합 옵션명의 id는 줄 수 없다(방식을 바꾸려면 새 옵션명으로 보낸다) */
-	groupId: z.string().optional(),
-	name: optionNameSchema,
-	required: z.boolean().default(false),
-	values: z.array(addonValueRequestSchema).min(1).max(100)
+/** 포트원 채널 목록 최소 개수. 결제수단을 받으려면 채널이 하나는 있어야 한다 */
+const PORTONE_MIN_CHANNELS = 1;
+/** 포트원 채널 목록 최대 개수 */
+const PORTONE_MAX_CHANNELS = 20;
+/** 포트원 채널 표시 이름 최대 길이 */
+const PORTONE_CHANNEL_NAME_MAX_LENGTH = 50;
+const portOneChannelSchema = z.object({
+	channelKey: z.string().trim().min(8).max(200).describe("포트원 콘솔 [연동 정보] > [채널 관리]의 채널 키. 공개 값"),
+	name: z.string().trim().max(50).nullable().optional().describe("채널 표시 이름 (예: 카드 전용)"),
+	payMethods: z.array(pgPaymentMethodSchema).min(1).max(pgPaymentMethodSchema.options.length).describe("이 채널로 받을 결제수단. 결제수단마다 먼저 나열된 채널이 쓰인다")
 });
-const customInputRequestSchema = z.object({
-	/** 전달 시 기존 항목 행을 유지(UPDATE). 생략하면 신규 발급 */
-	inputId: z.string().optional(),
-	label: z.string().trim().min(1).max(30),
-	placeholder: z.string().trim().max(100).nullish(),
-	maxLength: z.number().int().min(1).max(200),
-	required: z.boolean().default(false),
-	usable: z.boolean().default(true)
+const portOneCredentialsInputSchema = z.object({
+	storeId: z.string().trim().min(8).max(200).describe("포트원 Store ID (`store-…`). 공개 값"),
+	channels: z.array(portOneChannelSchema).min(1).max(20).describe("채널 목록. 포트원 V2는 PG·결제수단별로 채널을 따로 추가하므로 여러 개를 등록할 수 있다"),
+	apiSecret: secretInput().optional().describe("V2 API Secret. 비밀 값. 최초 연결 시 필수, 수정 시 생략하면 기존 값을 유지한다"),
+	webhookSecret: secretInput().nullable().optional().describe("웹훅 서명 검증용 시크릿. 비밀 값. 생략하면 기존 값 유지, null이면 삭제")
 });
-/**
-* 주문상품·장바구니·주문서 줄의 옵션 선택 스냅샷 한 칸 — 주문 시점 이름이다(상품을 고쳐도 바뀌지 않는다).
-* 조합 옵션은 옵션명마다 한 칸이고 추가금은 조합 단위라 0이다(조합 추가금은 단가에 들어 있다). 추가 선택은 값의 추가금이다.
-*/
-const optionSelectionSchema = z.object({
-	kind: z.string().describe("옵션명 방식. 현재 값은 `combination`·`addon`이고 값이 추가될 수 있어 문자열로 받는다"),
-	groupName: z.string(),
-	valueName: z.string(),
-	additionalPrice: z.number().int()
+const upsertEnvironment = () => pgEnvironmentSchema.describe("저장할 자격 증명 세트. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 세트를 따로 둔다. 어느 세트로 결제할지는 이 값이 아니라 샌드박스 스위치(`sandboxMode`)가 정한다");
+const upsertTossPaymentsProviderRequestSchema = z.object({
+	environment: upsertEnvironment(),
+	credentials: tossPaymentsCredentialsInputSchema
 });
-/** 구매자가 적은 직접 입력값 — 주문 시점 항목명과 값 */
-const customInputValueSchema = z.object({
-	label: z.string(),
-	value: z.string()
+const upsertPortOneProviderRequestSchema = z.object({
+	environment: upsertEnvironment(),
+	credentials: portOneCredentialsInputSchema
 });
-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 updatePaymentProviderRequestSchema = z.object({
+	enabled: z.boolean().optional().describe("사용 여부. 켜려면 활성 환경(샌드박스면 TEST, 아니면 LIVE) 자격 증명이 모두 저장돼 있어야 한다(`PAYMENT_PROVIDER_INCOMPLETE`)"),
+	sandboxMode: z.boolean().optional().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(항상 허용). `false`(라이브 전환)는 라이브 개방 조건을 모두 충족해야 한다(`LIVE_GATE_NOT_MET`)"),
+	easyPayProviders: z.array(easyPayProviderSchema).max(easyPayProviderSchema.options.length).optional().describe("이 PG로 받는 간편결제사 — 통째로 바꾼다. PG 계약(포트원은 채널)에 추가한 간편결제만 켠다. 켠 간편결제사마다 스토어프론트 결제 옵션이 하나씩 생긴다(포트원은 간편결제를 받는 채널이 있어야 한다)")
+}).refine((body) => body.enabled !== void 0 || body.sandboxMode !== void 0 || body.easyPayProviders !== void 0, { message: "enabled·sandboxMode·easyPayProviders 중 하나는 보내야 합니다" });
+const verifyPaymentProviderRequestSchema = z.object({ environment: pgEnvironmentSchema.optional().describe("연결 테스트할 자격 증명 세트. 생략하면 활성 환경(샌드박스면 TEST, 아니면 LIVE)") });
+const updatePaymentSettingsRequestSchema = z.object({
+	priority: z.array(pgProviderSchema).min(1).max(50).optional().describe("PG 우선순위(앞이 1순위) — 스토어프론트 결제 옵션 목록의 PG 순서다. 연결된 PG 수만큼 **모두 한 번씩** 나열한다(길이 상한 50은 안전장치다). 빠지거나 중복되거나 연결되지 않은 PG가 있으면 `INVALID_PRIORITY`"),
+	checkoutOrigins: z.array(z.string().max(200)).max(20).optional().describe("결제 도메인 — 통째로 바꾼다. 결제를 마친 구매자가 돌아올 스토어프론트 origin(`https://shop.example.com`, https·경로 없음). 결제 시작의 `returnUrl`은 이 목록 안이어야 한다. 비어 있으면 실결제를 시작할 수 없다(테스트 결제는 localhost 허용). 같은 도메인을 PG 가맹 정보에도 등록한다. 형식이 틀리면 `INVALID_CHECKOUT_ORIGIN`")
+}).refine((body) => body.priority !== void 0 || body.checkoutOrigins !== void 0, { message: "priority 또는 checkoutOrigins 중 하나는 보내야 합니다" });
+const maskedSecretSchema = z.object({
+	field: z.string().describe("비밀 필드 이름 (`secretKey`·`apiSecret`·`webhookSecret`)"),
+	configured: z.boolean().describe("값이 저장돼 있는가"),
+	masked: z.string().nullable().describe("앞 4자리만 남긴 마스킹 값 (예: `test****`). 저장되지 않았으면 null")
 });
-const productSchema = productSummarySchema.extend({
-	description: z.string().optional(),
-	/**
-	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
-	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
-	*/
-	descriptionJson: z.string().nullable().optional(),
-	originalPrice: z.number().int().nullable().optional().describe("정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액 계산에 쓰지 않는다 — 구매자가 내는 가격은 즉시할인이 있으면 `discountedPrice`, 없으면 `salePrice`다. 스토어프론트 상품 응답에도 같은 값이 실린다. 정하지 않았으면 null"),
-	images: z.array(z.url()).optional(),
-	attributes: z.array(z.object({
-		attributeId: z.string(),
-		value: z.string()
-	})).optional(),
-	optionGroups: z.array(optionGroupSchema),
-	/** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
-	variants: z.array(productVariantSchema),
-	addonGroups: z.array(addonGroupSchema).optional().default([]).describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
-	customInputs: z.array(customInputSchema).optional().default([]).describe("직접 입력 항목(이슈 #59). 사용하지 않는 항목도 싣는다. 없으면 빈 배열. 서버는 항상 싣는다"),
-	optionSort: optionSortSchema.optional().default("REGISTERED").describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다"),
-	fulfillment: productFulfillmentResponseSchema,
-	fulfillmentTypeLocked: z.boolean().describe("판매 이력(주문상품)이 있어 상품 유형(`fulfillment.type`)을 바꿀 수 없는가. true면 다른 유형으로 수정하는 요청이 409 `FULFILLMENT_TYPE_LOCKED`다. 같은 유형 안의 속성은 바꿀 수 있다"),
-	refundPolicy: productRefundPolicyPatchSchema.nullable().describe("상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 상점 기본 환불 정책을 쓴다. 반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 있다"),
-	/**
-	* 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
-	* 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
-	*/
-	discount: discountSchema.nullable().optional().describe("설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null"),
-	createdAt: z.string().optional()
+const publicConfigSchema = z.union([z.object({ clientKey: z.string() }), z.object({
+	storeId: z.string(),
+	channels: z.array(portOneChannelSchema)
+})]);
+const verificationSchema = z.object({
+	result: pgVerificationResultSchema,
+	message: z.string().nullable(),
+	checkedAt: z.string()
+});
+const paymentCredentialSetSchema = z.object({
+	environment: pgEnvironmentSchema,
+	publicConfig: publicConfigSchema.describe("공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`"),
+	secrets: z.array(maskedSecretSchema).describe("비밀 값의 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+	lastVerification: verificationSchema.nullable().describe("이 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+	updatedAt: z.string()
+});
+const liveGateConditionCodeSchema = z.enum([
+	"TEST_CONNECTION",
+	"SANDBOX_PAYMENT",
+	"SANDBOX_REFUND",
+	"LIVE_CONNECTION",
+	"PLATFORM_LIVE_ENABLED"
+]).describe("라이브 개방 조건. `TEST_CONNECTION`=TEST 세트 연결 테스트 성공, `SANDBOX_PAYMENT`=현재 TEST 세트로 샌드박스 결제 1건 승인, `SANDBOX_REFUND`=그 샌드박스 결제의 환불 1건 성공, `LIVE_CONNECTION`=LIVE 세트 연결 테스트 성공, `PLATFORM_LIVE_ENABLED`=플랫폼이 실결제를 열어 둠");
+const liveGateConditionSchema = z.object({
+	code: liveGateConditionCodeSchema,
+	met: z.boolean().describe("충족 여부"),
+	message: z.string().describe("조건 설명 또는 미충족 사유")
+});
+const liveGateSchema = z.object({
+	status: z.enum(["LOCKED", "OPEN"]).describe("`OPEN`=조건을 모두 충족해 샌드박스를 끌 수 있다, `LOCKED`=아직 끌 수 없다"),
+	conditions: z.array(liveGateConditionSchema),
+	openedAt: z.string().nullable().describe("마지막으로 라이브로 전환한 시각. 없으면 null")
 });
-/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
-const MAX_PRODUCT_IMAGES = 10;
 /**
-* 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
-*
-* https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
-* **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
-* 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
-*
-* 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
-* 만들면 상품 조회 자체가 막힌다.
+* 409 `LIVE_GATE_NOT_MET`·`LIVE_PAYMENTS_DISABLED`의 `ApiError.details` 형태.
+* 응답 파싱용이라 관대하다 — 알 수 없는 키는 버리고, 형태가 다르면 safeParse 실패로 처리한다.
 */
-const productImageUrlSchema = z.url().max(2048).describe("상품 이미지 주소. https만 허용하고, 확장자가 있으면 이미지 형식이어야 한다");
+const liveGateErrorDetailsSchema = z.object({ conditions: z.array(liveGateConditionSchema).describe("라이브 개방 조건별 충족 여부 (순서 고정)") });
+const paymentProviderSchema = z.object({
+	provider: pgProviderSchema,
+	displayName: z.string().describe("표시 이름 (토스페이먼츠·포트원)"),
+	connected: z.boolean().describe("자격 증명이 저장돼 있는가"),
+	enabled: z.boolean().describe("결제에 사용 중인가"),
+	priority: z.number().int().nullable().describe("우선순위 (1이 가장 높다). 연결되지 않았으면 null"),
+	environment: pgEnvironmentSchema.nullable().describe("새 결제에 쓰는 환경(활성 환경). 샌드박스 스위치가 켜져 있으면 `TEST`, 꺼져 있으면 `LIVE`. 연결되지 않았으면 null"),
+	publicConfig: publicConfigSchema.nullable().describe("활성 환경 세트의 공개 값. 토스페이먼츠는 `{clientKey}`, 포트원은 `{storeId, channels}`. 활성 세트가 없으면 null"),
+	secrets: z.array(maskedSecretSchema).describe("활성 환경 세트의 비밀 값 저장 여부와 마스킹. 평문은 어떤 응답에도 나오지 않는다"),
+	lastVerification: verificationSchema.nullable().describe("활성 환경 세트의 마지막 연결 테스트 결과. 세트를 바꾸면 초기화된다"),
+	updatedAt: z.string().nullable(),
+	sandboxMode: z.boolean().describe("샌드박스 스위치. `true`면 새 결제에 TEST 세트를 쓴다(실제로 돈이 오가지 않는다). 연결되지 않았으면 true"),
+	credentialSets: z.object({
+		TEST: paymentCredentialSetSchema.nullable(),
+		LIVE: paymentCredentialSetSchema.nullable()
+	}).describe("환경별 자격 증명 세트. 등록되지 않은 세트는 null"),
+	liveGate: liveGateSchema.describe("라이브 개방 조건. 조건을 모두 충족해야 샌드박스를 끌 수 있다"),
+	easyPayProviders: z.array(easyPayProviderResponseSchema).describe("이 PG로 받는 간편결제사. 연결되지 않았으면 빈 목록. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
+	retiredCredentialCount: z.number().int().describe("보관된(가맹점 교체·연결 해제로 새 결제에 더 쓰이지 않는) 자격 증명 수. 그 가맹점으로 받은 결제의 환불·대사에 계속 쓰인다"),
+	routingExclusion: z.string().nullable().optional().default(null).describe("지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(상점 플랫폼이 다시 계산하지 않는다). 후보가 아닌 PG에는 항상 사유 코드를 붙인다(연결 안 된 PG 포함) — 모든 PG는 `candidates`에 있거나 이 값이 null이 아니다. 현재 값: `NOT_CONNECTED`(연결 안 됨) · `DISABLED`(사용 중지) · `CREDENTIAL_MISSING`(활성 환경 자격 증명 없음) · `SANDBOX_IN_LIVE_STORE`(다른 PG가 라이브라 이 샌드박스 PG는 실구매자 결제에 쓰지 않음) · `PLATFORM_BLOCKED`(플랫폼이 실결제를 막음) · `MODE_MISMATCH`(라이브를 연 서버 모드와 현재 모드가 다름). 값이 추가될 수 있어 문자열로 받는다 — 모르는 값은 후보 아님으로 다룬다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다")
+});
 /**
-* 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
-*
-* - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
-*   상세 화면에 박히는 주입 경로가 된다.
-* - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
-* - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
-*   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+* `PaymentProvider.routingExclusion`의 현재 값 — 응답 스키마는 서버가 사유를 추가해도 파싱이 깨지지 않게 문자열로 받는다.
+* 화면 문구 분기는 이 목록으로 하고, 모르는 값은 "후보 아님"으로 다룬다.
 */
-function productImageRejection(url) {
-	if (url.length > 2048) return {
-		code: "INVALID_IMAGE_URL",
-		message: "이미지 주소가 너무 깁니다"
-	};
-	let parsed;
-	try {
-		parsed = new URL(url);
-	} catch {
-		return {
-			code: "INVALID_IMAGE_URL",
-			message: "이미지 주소 형식이 아닙니다"
-		};
-	}
-	if (parsed.protocol !== "https:") return {
-		code: "INVALID_IMAGE_URL",
-		message: "이미지 주소는 https로 시작해야 합니다"
-	};
-	const extension = uploadExtensionOf(parsed.pathname);
-	const allowed = UPLOAD_PURPOSE_LIMITS["product-image"].extensions;
-	if (extension && !allowed.includes(extension)) return {
-		code: "UNSUPPORTED_FILE_TYPE",
-		message: `상품 이미지는 ${allowed.join(", ")}만 쓸 수 있습니다`
-	};
-	return null;
-}
+const PAYMENT_ROUTING_EXCLUSION_CODES = [
+	"NOT_CONNECTED",
+	"DISABLED",
+	"CREDENTIAL_MISSING",
+	"SANDBOX_IN_LIVE_STORE",
+	"PLATFORM_BLOCKED",
+	"MODE_MISMATCH"
+];
 /**
-* 식별 코드 — 빈 문자열·공백만 있는 값은 거부한다.
-* `""`를 통과시키면 서버 중복 사전 검사(falsy skip)와 DB partial unique
-* (`WHERE ... is not null`)의 판정이 갈려 409 대신 500이 나간다.
+* 결제수단 반복 실패 경고(#86 후속) — 같은 PG·결제수단(·간편결제사)이 가맹점 설정 문제(구매자가 고칠 수 없는 실패, 예: KG이니시스
+* `V105 [NO MPI SET] 전용화면 미설정`)로 기간 안에 여러 번 실패했다. 구매자에게는 「이 결제수단은 지금 사용할 수 없습니다」가 보이고,
+* PG 관리자에서 그 결제수단의 전용 화면·채널을 설정해야 다시 쓸 수 있다
 */
-const codeSchema = z.string().trim().min(1).max(64);
-const optionValueRequestSchema = z.object({
-	/** 전달 시 기존 값 행을 유지(UPDATE). 생략하면 신규 발급 */
-	valueId: z.string().optional(),
-	name: z.string().min(1).max(50)
+const paymentFailureWarningSchema = z.object({
+	provider: z.string().describe("PG(`tosspayments`·`portone`). 값이 추가될 수 있어 문자열로 받는다"),
+	method: z.string().describe("결제수단(`CARD`·`BANK_TRANSFER`·`VIRTUAL_ACCOUNT`·`MOBILE`·`EASY_PAY`)"),
+	easyPayProvider: easyPayProviderResponseSchema.nullable().describe("간편결제사. 간편결제가 아니면 null"),
+	code: z.string().nullable().describe("PG 실패 코드(예: `V105`, `AllChannelsNotSatisfied`). PG 원문 문구로만 판정했으면 null"),
+	count: z.number().int().describe("기간 안의 실패 횟수"),
+	lastAt: z.string().describe("마지막 실패 시각"),
+	message: z.string().nullable().describe("마지막 실패의 PG 원문 사유. 구매자에게는 보이지 않는다")
 });
-const optionGroupRequestSchema = z.object({
-	/** 전달 시 기존 축 행을 유지(UPDATE). 생략하면 신규 발급 */
-	groupId: z.string().optional(),
-	name: z.string().min(1).max(50),
-	values: z.array(optionValueRequestSchema).min(1).max(100)
+const paymentSettingsSchema = z.object({
+	checkoutOrigins: z.array(z.string()).describe("결제 도메인 — 결제를 마친 구매자가 돌아올 스토어프론트 origin 목록"),
+	providers: z.array(paymentProviderSchema).describe("지원하는 모든 PG. 연결된 것은 우선순위순, 연결되지 않은 것은 뒤에 온다"),
+	environment: pgEnvironmentSchema.nullable().optional().default(null).describe("지금 결제를 시작하면 쓰는 결제 환경. 사용 가능한 PG 중 하나라도 라이브면 `LIVE`(샌드박스 PG는 제외), 아니면 `TEST`. 사용 가능한 PG가 없으면 null. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(null)으로 읽는다"),
+	candidates: z.array(z.string()).optional().default(() => []).describe("지금 결제를 시작하면 쓰는 PG, 우선순위순(`tosspayments`·`portone`). 비어 있으면 구매자가 결제할 수 없다. 빠진 PG의 사유는 `providers[].routingExclusion` — 후보가 아닌 PG에는 항상 사유 코드를 붙인다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다"),
+	warnings: z.array(paymentFailureWarningSchema).optional().default(() => []).describe("최근 24시간 안에 같은 PG·결제수단·간편결제사가 가맹점 설정 문제로 3번 이상 실패한 조합, 마지막 실패가 최근인 순. 판정 규칙은 서버가 정하고 바뀔 수 있다. 서버는 항상 싣는다. 이 필드가 없는 이전 서버 응답은 기본값(빈 배열)으로 읽는다")
+});
+const paymentProviderVerificationSchema = z.object({
+	provider: pgProviderSchema,
+	environment: pgEnvironmentSchema.describe("연결 테스트한 자격 증명 세트"),
+	result: pgVerificationResultSchema,
+	message: z.string().nullable().describe("실패 사유 또는 참고 메시지"),
+	checkedAt: z.string()
+});
+const salesReportGroupBySchema = z.enum([
+	"DAY",
+	"PROVIDER",
+	"METHOD",
+	"PROVIDER_METHOD"
+]).describe("행 집계 기준. 기본 `DAY`");
+const reportDate = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
+const salesReportQuerySchema = z.object({
+	from: reportDate.describe("시작일 (YYYY-MM-DD, Asia/Seoul 기준, 포함)"),
+	to: reportDate.describe("종료일 (YYYY-MM-DD, 포함). from부터 최대 92일"),
+	provider: pgProviderSchema.optional().describe("PG 필터"),
+	method: pgPaymentMethodSchema.optional().describe("결제수단 필터 — **실제 결제수단**(PG가 보고한 수단, 모르면 요청 수단) 기준. 결제창에서 결제수단이 바뀔 수 있다(카드 결제창의 간편결제 탭 등). 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다"),
+	groupBy: salesReportGroupBySchema.optional(),
+	includeTest: z.enum(["true", "false"]).optional().describe("테스트 결제(샌드박스 결제) 포함 여부. 기본 `false` — 테스트 결제의 승인·환불은 집계에서 빠진다")
 });
-const productVariantRequestSchema = z.object({
-	/** 기존 variant 유지 시 전달. 생략하면 신규 생성 */
-	variantId: z.string().optional(),
-	/** optionGroups 순서대로 각 축에서 고른 값 이름. 서버가 이름 → valueId를 해석한다 */
-	valueNames: z.array(z.string()).default([]),
-	additionalPrice: z.number().int().default(0),
-	/**
-	* 생략 = 기존 재고 유지 (신규 variant는 0).
-	* 구조 교체(PUT)가 폼 로드 시점의 재고를 되쓰지 않게 하는 옵트인 필드다 —
-	* 재고만 바꿀 때는 PATCH /products/{id}/variants/{variantId}/stock을 쓴다.
-	*/
-	stockQuantity: z.number().int().min(0).optional(),
-	sku: codeSchema.optional(),
-	barcode: codeSchema.optional(),
-	costPrice: z.number().int().min(0).optional(),
-	weightGram: z.number().int().min(0).optional(),
-	sellerCode: codeSchema.optional(),
-	usable: z.boolean().default(true)
+const salesTotalsSchema = z.object({
+	paymentCount: z.number().int().describe("승인 건수"),
+	paymentAmount: z.number().int().describe("승인 금액 합계"),
+	refundCount: z.number().int().describe("환불(취소) 건수. 부분 취소도 1건"),
+	refundAmount: z.number().int().describe("환불 금액 합계"),
+	netAmount: z.number().int().describe("순매출 = 승인 금액 - 환불 금액"),
+	pgFeeAmount: z.number().int().nullable().describe("PG 수수료 (참고용). PG에서 확정 값을 받지 못하면 null")
 });
-/** 축 × 값 → variant 전체 교체 요청 (PUT /products/{productId}/options) */
-const optionModelRequestSchema = z.object({
-	optionGroups: z.array(optionGroupRequestSchema).max(3).default([]),
-	variants: z.array(productVariantRequestSchema).min(1).max(500),
-	addonGroups: z.array(addonGroupRequestSchema).max(5).optional().describe("추가 선택 옵션명 전체(이슈 #59). 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 끄려면 빈 배열을 보낸다. 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다"),
-	customInputs: z.array(customInputRequestSchema).max(5).optional().describe("직접 입력 항목 전체(이슈 #59). 배열 순서가 표시 순서다. 주면 통째로 바꾸고, 생략하면 등록은 없음·수정은 현재 값을 그대로 둔다. 항목명에 개인정보성 단어(`CUSTOM_INPUT_FORBIDDEN_WORDS`)가 있으면 400 `CUSTOM_INPUT_LABEL_FORBIDDEN`, 기능이 열리기 전에는 비어 있지 않은 값이 409 `OPTION_ADDONS_UNAVAILABLE`이다"),
-	optionSort: optionSortSchema.optional().describe("옵션 값 정렬 순서(이슈 #59). 서버가 이 순서로 값의 `sortOrder`를 다시 매긴다. 생략하면 등록은 `REGISTERED`, 수정은 현재 값이다")
+const salesReportRowSchema = salesTotalsSchema.extend({
+	date: z.string().nullable().describe("일자 (YYYY-MM-DD, Asia/Seoul). groupBy=DAY일 때만 값"),
+	provider: pgProviderSchema.nullable().describe("PG. groupBy에 PROVIDER가 포함될 때만 값"),
+	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단(PG가 보고한 수단, 모르면 요청 수단). groupBy에 METHOD가 포함될 때만 값. 관리 주문 API의 method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다")
 });
-/** GET /products/{productId}/options 응답 */
-const optionModelSchema = z.object({
-	optionGroups: z.array(optionGroupSchema),
-	variants: z.array(productVariantSchema),
-	addonGroups: z.array(addonGroupSchema).optional().default([]).describe("추가 선택 옵션명(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
-	customInputs: z.array(customInputSchema).optional().default([]).describe("직접 입력 항목(이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다"),
-	optionSort: optionSortSchema.optional().default("REGISTERED").describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다")
+const salesReportSchema = z.object({
+	from: z.string(),
+	to: z.string(),
+	timezone: z.literal("Asia/Seoul"),
+	currency: z.literal("KRW"),
+	groupBy: salesReportGroupBySchema,
+	provider: pgProviderSchema.nullable().describe("적용된 PG 필터"),
+	method: pgPaymentMethodSchema.nullable().describe("적용된 결제수단 필터"),
+	includeTest: z.boolean().describe("테스트 결제(샌드박스 결제)를 집계에 포함했는가"),
+	summary: salesTotalsSchema.describe("기간 전체 합계"),
+	rows: z.array(salesReportRowSchema).describe("집계 행. 활동이 없는 날짜·PG는 생략된다")
 });
 /**
-* 재고 변경 택일 위반 문구 — SDK `.refine`과 서버 DomainException이 공유하는 단일 원천.
-* 경로에 따라 셀러가 다른 문구를 받지 않게 한다.
+* 결제 내역 — 결제 건(세션) 단위 공개 상태. 주문 단위 상태와 다르다.
+* - `APPROVED`: 승인됐고 환불이 없다
+* - `PARTIALLY_REFUNDED`·`REFUNDED`: 승인 뒤 일부·전액을 환불했다
+* - `PENDING`: 승인 결과를 아직 확정하지 못했다(대사 잡이 확정한다)
+* - `FAILED`: 승인되지 않고 끝났다(거절·준비 장애·구매자 취소·만료)
 */
-const VARIANT_STOCK_EXCLUSIVE_MESSAGE = "stockQuantity 또는 adjustment 중 하나만 전달해야 합니다";
+const paymentRecordStatusSchema = z.enum([
+	"APPROVED",
+	"PARTIALLY_REFUNDED",
+	"REFUNDED",
+	"PENDING",
+	"FAILED"
+]);
+const paymentAttemptStatusSchema = z.string().describe("시도 상태 — ready·approving·approved·unknown·declined·prepare_failed·canceled·failed·abandoned·voided. 새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다");
 /**
-* variant 재고 변경 요청 — 절대값(`stockQuantity`) 또는 증감(`adjustment`) 택일.
-* 서버도 같은 규칙을 400 VALIDATION_FAILED로 검증한다(이중 방어).
+* 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
+* - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
+* - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
+* - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
+* - `CANCELED`: 전액 환불로 취소됐다
+* - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
+* - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
 */
-const variantStockRequestSchema = z.object({
-	stockQuantity: z.number().int().min(0).optional(),
-	adjustment: z.number().int().optional()
-}).refine((v) => v.stockQuantity !== void 0 !== (v.adjustment !== void 0), { message: VARIANT_STOCK_EXCLUSIVE_MESSAGE });
-/** PATCH /products/{productId}/variants/{variantId}/stock 응답 */
-const variantStockSchema = z.object({
-	variantId: z.string(),
-	stockQuantity: z.number().int()
+const CASH_RECEIPT_STATUS_VALUES = [
+	"REQUESTED",
+	"PENDING",
+	"ISSUED",
+	"CANCELED",
+	"FAILED",
+	"SKIPPED"
+];
+const cashReceiptSchema = z.object({
+	cashReceiptId: z.string(),
+	status: z.string().describe("상태. `REQUESTED` 결제 전 · `PENDING` 발급 대기 · `ISSUED` 발급 · `CANCELED` 취소 · `FAILED` 실패 · `SKIPPED` 발급 대상 아님. 값이 추가될 수 있다"),
+	type: z.string().describe("용도. `INCOME_DEDUCTION` 소득공제 · `EXPENSE_PROOF` 지출증빙"),
+	identityType: z.string().describe("식별 번호 종류. `PHONE` 휴대폰 · `CARD` 현금영수증카드 · `BUSINESS` 사업자등록번호"),
+	identityNumberMasked: z.string().describe("가린 식별 번호 (예: 010****5678). 원문은 조회할 수 없다"),
+	amount: z.number().int().describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
+	issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
+	provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+	issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
+	receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
+	issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
+	canceledAt: z.string().nullable().describe("최근 취소 시각 (ISO 8601)"),
+	failCode: z.string().nullable().describe("마지막 실패 코드. 성공하면 비운다"),
+	failMessage: z.string().nullable().describe("마지막 실패 사유"),
+	reissuable: z.boolean().describe("상점 플랫폼 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
+	requestedAt: z.string().describe("신청 시각 (ISO 8601)"),
+	updatedAt: z.string().describe("마지막 변경 시각 (ISO 8601)")
 });
-/** 상품 쓰기 요청의 이미지 목록 — 등록·전체 수정·부분 수정이 같은 항목 형식을 쓴다. 첫 장이 대표(썸네일)다 */
-const productImagesRequestSchema = z.array(productImageUrlSchema).min(1).max(10);
-/**
-* 상품 쓰기 요청의 공통 필드 — 등록(POST)과 전체 수정(PUT)이 같다. 이행(`fulfillment`)만 두 요청의 스키마가 다르다.
-*
-* 최상위가 `strictObject`다. 모르는 필드는 400이다 — 이슈 #57 이전의 평면 필드(`deliveryFee`·`fulfillmentType`·`returnFee` 등)를
-* 보낸 요청이 조용히 무시되지 않게 한다. 옛 필드는 `fulfillment.{유형}.…`과 `refundPolicy`로 옮겼다.
-*/
-const productWriteShape = {
-	name: z.string().min(1).max(100),
-	categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
-	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)").describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
-	originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액은 판매가(즉시할인이 있으면 할인 적용가)다. 스토어프론트가 판매가보다 클 때 취소선·할인율로 보인다. 즉시할인은 `PUT /v1/products/{productId}/discount`로 따로 정한다"),
-	description: z.string().optional(),
-	/**
-	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
-	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
-	*/
-	descriptionJson: z.string().nullable().optional(),
-	images: productImagesRequestSchema.optional().describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
-	attributes: z.array(z.object({
-		attributeId: z.string(),
-		value: z.string()
-	})).optional(),
-	refundPolicy: productRefundPolicyPatchSchema.nullish().describe("상품별 환불 정책 — 준 항목만 상점 기본을 덮어쓴다. `null`이나 생략은 상점 기본을 그대로 쓴다는 뜻이다. 반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)"),
-	...optionModelRequestSchema.shape,
-	sourceOptionSetIds: z.array(z.string()).max(10).optional().describe("쓰기 전용(이슈 #59) — 이 저장으로 옵션을 불러온 저장 옵션 id. 상품 저장과 같은 트랜잭션에서 불러오기 기록을 남겨 저장 옵션의 `importedProductCount`를 센다. 없는 id는 무시한다")
-};
-const productCreateRequestSchema = z.strictObject({
-	...productWriteShape,
-	fulfillment: productFulfillmentCreateSchema.optional().describe("상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 생략하면 배송 상품(기본값)이다. 배송 상품이 아닌 유형은 판매가 열린 유형만 등록할 수 있다(409 `FULFILLMENT_TYPE_NOT_AVAILABLE`)")
+const paymentRecordSchema = z.object({
+	paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
+	orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
+	orderName: z.string().describe("주문명 (예: 무선 이어폰 프로 외 1건)"),
+	customerName: z.string().describe("구매자명"),
+	status: paymentRecordStatusSchema,
+	amount: z.number().int().describe("결제 금액"),
+	refundedAmount: z.number().int().describe("환불 완료 금액 합계. 실패한 환불은 빼고 센다"),
+	provider: pgProviderSchema.nullable().describe("승인한 PG. 승인 전에 끝났으면 마지막 시도의 PG"),
+	method: pgPaymentMethodSchema.nullable().describe("실제 결제수단. 모르면 요청 수단"),
+	easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("간편결제사. `method`가 `EASY_PAY`일 때만 값이 있고, PG가 알려 주지 않았으면 요청한 간편결제사다. 그 밖의 결제수단과 간편결제 이전 결제는 null. 서버는 항상 싣는다. 현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다"),
+	environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
+	testPayment: z.boolean().describe("샌드박스 결제인가"),
+	pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
+	attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
+	attemptCount: z.number().int().describe("시도 횟수"),
+	failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
+	failMessage: z.string().nullable().describe("실패 사유"),
+	paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
+	createdAt: z.string().describe("결제 시작 시각 (ISO 8601)"),
+	cashReceiptStatus: z.string().nullable().optional().default(null).describe("현금영수증 상태(`cashReceiptSchema.status`와 같은 값). 신청이 없으면 null. 서버는 항상 싣는다")
 });
-const fulfillmentUpdateDescription = "상품 이행. 생략하면 바꾸지 않는다. 주면 유형 안 필드를 모두 담아 통째로 바꾼다(현재 값과 병합하지 않는다). 판매 이력이 있으면 유형을 바꿀 수 없다(409 `FULFILLMENT_TYPE_LOCKED`)";
-/** 전체 수정(PUT) — 공통 필드는 등록과 같고, 이행은 생략하면 현재 값 유지, 주면 필드가 모두 필수다 */
-const productReplaceRequestSchema = z.strictObject({
-	...productWriteShape,
-	fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription)
+const paymentRecordPageSchema = pageSchema(paymentRecordSchema);
+const paymentAttemptRecordSchema = z.object({
+	attemptId: z.string(),
+	sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
+	provider: pgProviderSchema,
+	status: paymentAttemptStatusSchema,
+	method: pgPaymentMethodSchema.describe("주문서에서 고른 결제수단"),
+	easyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("주문서에서 고른 간편결제사. 간편결제가 아니면 null. 서버는 항상 싣는다(값이 추가될 수 있어 문자열)"),
+	approvedMethod: pgPaymentMethodSchema.nullable().describe("PG가 보고한 실제 결제수단"),
+	approvedEasyPayProvider: easyPayProviderResponseSchema.nullable().optional().default(null).describe("PG가 보고한 실제 간편결제사. 모르거나 간편결제가 아니면 null. 서버는 항상 싣는다(값이 추가될 수 있어 문자열)"),
+	amount: z.number().int(),
+	environment: pgEnvironmentSchema,
+	pgTransactionId: z.string().nullable(),
+	failCode: z.string().nullable(),
+	failMessage: z.string().nullable(),
+	createdAt: z.string(),
+	updatedAt: z.string()
 });
-const productPatchRequestSchema = z.strictObject({
-	name: z.string().max(100).optional(),
-	salePrice: z.number().int().multipleOf(10).optional(),
-	status: productStatusSchema.optional(),
-	images: productImagesRequestSchema.optional().describe("상품 이미지 주소 목록. 주면 통째로 바꾼다(현재 목록과 병합하지 않는다). 첫 장이 대표 이미지(썸네일)다. 생략하면 바꾸지 않는다"),
-	fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
-	refundPolicy: productRefundPolicyPatchSchema.nullable().optional().describe("상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 상점 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 상점 기본을 따른다. 생략하면 바꾸지 않는다")
-}).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
-const productSortSchema = z.enum([
-	"createdAt.desc",
-	"createdAt.asc",
-	"salePrice.asc",
-	"salePrice.desc",
-	"updatedAt.desc"
-]);
-/** `GET /v1/products` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
-const productListQuerySchema = z.object({
-	status: productStatusSchema.optional().describe("판매 상태 필터"),
-	categoryId: z.string().optional().describe("카테고리 필터 — 하위 카테고리의 상품도 포함"),
-	keyword: z.string().optional().describe("상품명 검색 (포함)"),
-	sellerCode: z.string().optional().describe("판매자 상품코드 — 이 코드가 붙은 variant를 가진 상품"),
-	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
-	...pageQueryShape()
+const paymentRefundRecordSchema = z.object({
+	refundId: z.string(),
+	amount: z.number().int(),
+	reason: z.string().describe("환불 사유 코드"),
+	kind: z.string().describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
+	status: z.string().describe("SUCCEEDED·FAILED"),
+	failMessage: z.string().nullable(),
+	requestedAt: z.string(),
+	completedAt: z.string().nullable()
 });
-const discountRequestSchema = z.object({
-	discountType: z.enum(["RATE", "AMOUNT"]),
-	discountValue: z.number().int().min(1),
-	startAt: z.string().optional(),
-	endAt: z.string().optional()
+const paymentRecordDetailSchema = paymentRecordSchema.extend({
+	refundableAmount: z.number().int().describe("환불 가능 잔액 = 승인 금액 - 환불 완료 금액"),
+	merchantId: z.string().nullable().describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
+	attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
+	refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다"),
+	cashReceipt: cashReceiptSchema.nullable().optional().default(null).describe("현금영수증. 구매자가 신청하지 않았으면 null. 서버는 항상 싣는다")
+});
+/** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
+const paymentListQuerySchema = z.object({
+	from: z.string().optional().describe("조회 시작 시각 (ISO 8601, 포함). 생략하면 최근 30일"),
+	to: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 기간은 최대 92일"),
+	status: z.string().optional().describe("결제 상태 필터 (PaymentRecordStatus)"),
+	provider: z.string().optional().describe("PG 필터"),
+	method: z.string().optional().describe("실제 결제수단 필터"),
+	keyword: z.string().optional().describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
+	includeTest: z.string().optional().describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
+	page: z.string().optional().describe("페이지 번호 (1부터)"),
+	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
 });
 //#endregion
 //#region src/schemas/order.ts
@@ -5561,6 +5743,25 @@ function createStoreClient(options) {
 			/** 상품의 현재 옵션을 저장 옵션으로 만든다(또는 `replaceOptionSetId`를 덮어쓴다) */
 			saveFromProduct: (body) => storeHttp.request("POST", "/saved-option-sets/from-product", savedOptionSetFromProductResultSchema, { body: savedOptionSetFromProductRequestSchema.parse(body) })
 		},
+		/**
+		* 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음(다대다). 권한은 카테고리와 같다(`category:r`·`category:rw`).
+		* 쓰기마다 `revision`이 오른다. 수정 본문에 읽은 `revision`을 주면 그 사이 다른 수정이 있을 때 409 `COLLECTION_CHANGED`다.
+		*/
+		collections: {
+			list: (params) => storeHttp.request("GET", "/collections", collectionPageSchema, { query: params }),
+			get: (collectionId) => storeHttp.request("GET", path`/collections/${collectionId}`, collectionSchema),
+			/** 주소가 겹치면 409 `COLLECTION_SLUG_TAKEN`, 상점당 200개를 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
+			create: (body) => storeHttp.request("POST", "/collections", collectionSchema, { body: collectionCreateRequestSchema.parse(body) }),
+			update: (collectionId, body) => storeHttp.request("PATCH", path`/collections/${collectionId}`, collectionSchema, { body: collectionPatchRequestSchema.parse(body) }),
+			remove: (collectionId) => storeHttp.requestVoid("DELETE", path`/collections/${collectionId}`),
+			/** 담긴 상품 — 직접 정한 순서 */
+			listProducts: (collectionId, params) => storeHttp.request("GET", path`/collections/${collectionId}/products`, pageSchema(collectionProductSchema), { query: params }),
+			/** 담긴 상품을 통째로 바꾼다(순서 포함) */
+			replaceProducts: (collectionId, body) => storeHttp.request("PUT", path`/collections/${collectionId}/products`, collectionSchema, { body: collectionProductsReplaceRequestSchema.parse(body) }),
+			/** 뒤에 붙인다. 이미 담긴 상품은 그 자리에 둔다 */
+			addProducts: (collectionId, body) => storeHttp.request("POST", path`/collections/${collectionId}/products`, collectionSchema, { body: collectionProductsAddRequestSchema.parse(body) }),
+			removeProduct: (collectionId, productId) => storeHttp.requestVoid("DELETE", path`/collections/${collectionId}/products/${productId}`)
+		},
 		categories: {
 			list: (params) => storeHttp.request("GET", "/categories", z.array(categorySchema), { query: params }),
 			tree: () => storeHttp.request("GET", "/categories", z.array(categoryTreeNodeSchema), { query: { tree: true } }),
@@ -6642,4 +6843,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, BUSINESS_INFO_MAX_LENGTH, BUSINESS_NUMBER_PATTERN, CASH_RECEIPT_STATUS_VALUES, COUPON_CODE_PATTERN, COUPON_CONDITIONS_DEFAULTS, COUPON_TARGET_ALL, COUPON_TARGET_LIST_MAX, CUSTOM_INPUT_FORBIDDEN_WORDS, FULFILLMENT_RULES, MAX_ADDON_GROUPS, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_CUSTOM_INPUTS, MAX_CUSTOM_INPUT_LENGTH, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_SAVED_OPTION_SETS, MAX_SAVED_OPTION_SET_NAME, 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, REFUND_POLICY_DEFAULTS, REFUND_POLICY_DELIVERY_FEE_KEYS, REMOTE_AREA_ZIP_RANGES, RESERVED_STOREFRONT_SLUGS, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STOREFRONT_BLOCKED_PATH_SEGMENTS, STOREFRONT_BUILD_STAGES, STOREFRONT_BUILD_TERMINAL_STATUSES, STOREFRONT_CHECK_TERMINAL_STATUSES, STOREFRONT_CUSTOM_DOMAIN_LIMIT_DEFAULT, STOREFRONT_DOMAIN_DNS_GRACE_DAYS, STOREFRONT_DOMAIN_DNS_WAIT_DAYS, STOREFRONT_DOMAIN_TXT_LABEL, STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES, STOREFRONT_EDIT_CAPACITY, STOREFRONT_EDIT_IDLE_MINUTES, STOREFRONT_EDIT_PREVIEW_SUFFIX, STOREFRONT_EDIT_START_STAGES, STOREFRONT_FILE_BATCH_MAX, STOREFRONT_FILE_MAX_BYTES, STOREFRONT_PATH_SEGMENT_PATTERN, STOREFRONT_PLATFORM_DOMAINS, STOREFRONT_PUBLIC_SUFFIXES, STOREFRONT_SEARCH_REGEX_MAX_LENGTH, STOREFRONT_SHOWCASE_SLUG_PREFIX, STOREFRONT_SITE_CREATE_LIMIT, STOREFRONT_SLUG_CHANGE_LIMIT, STOREFRONT_SLUG_CHANGE_WINDOW_DAYS, STOREFRONT_SLUG_HOLD_DAYS, STOREFRONT_SLUG_PATTERN, STOREFRONT_SOURCE_BLOB_BATCH_MAX, STOREFRONT_SOURCE_PART_BYTES, STOREFRONT_WORKSPACE_MAX_BYTES, STOREFRONT_WORKSPACE_MAX_FILES, 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_COUNT_WARNING, 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, addStorefrontDomainRequestSchema, addonGroupRequestSchema, addonGroupSchema, addonValueRequestSchema, addonValueSchema, 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, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, businessInfoPatchShape, businessInfoResponseShape, businessNumberSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeStorefrontSlugRequestSchema, changeStorefrontTemplateRequestSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, 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, createStorefrontEditPreviewLinkRequestSchema, createStorefrontPreviewLinkRequestSchema, createStorefrontSiteRequestSchema, createStorefrontVersionRequestSchema, customInputLabelForbiddenWord, customInputRequestSchema, customInputSchema, customInputValueSchema, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerCouponSchema, customerDelegationRequestSchema, customerDelegationSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deleteStorefrontFileRequestSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, disableStorefrontHostingRequestSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, fulfillBulkRequestSchema, fulfillRequestSchema, fulfillmentRuleOf, fulfillmentTypeOf, fulfillmentTypeResponseSchema, fulfillmentTypeSchema, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isCouponTargetLine, isEditableStorefrontPath, isReservedStoreCode, isReservedStorefrontSlug, isShowcaseStorefrontSlug, isStoreScope, isWebOrigin, issueCouponRequestSchema, issueCouponResultSchema, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, mcpRuleResultSchema, mcpToolEventSchema, moveStorefrontFileRequestSchema, myAccountSchema, myStoreSchema, normalizeBusinessNumber, normalizeCouponCode, normalizeStorefrontHostname, normalizeStorefrontPath, oauthTokenResponseSchema, openFulfillmentUnion, optionGroupKindSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionSelectionSchema, optionSortSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderDiscountSchema, orderFulfilledWebhookEventDataSchema, orderFulfilledWebhookEventSchema, orderItemFulfillmentSchema, orderItemFulfillmentSnapshotResponseSchema, orderItemFulfillmentSnapshotSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentFailureWarningSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, planCodeSchema, planEntitlementsSchema, planErrorDetailsSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productFulfillmentCreateSchema, productFulfillmentResponseSchema, productFulfillmentSchema, productFulfillmentUpdateSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productRefundPolicyPatchSchema, productReplaceRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedPaidRefundBase, proratedRefundBase, publicPlanSchema, publicPlansSchema, publishStorefrontVersionRequestSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, quotePricing, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, replaceStorefrontSourceRequestSchema, requiresCollection, requiresShipping, resolveRefundPolicy, resolveShippingPolicy, responsePlanCodeSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, rollbackStorefrontRequestSchema, runStorefrontCheckRequestSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, savedCustomInputRequestSchema, savedCustomInputSchema, savedOptionGroupRequestSchema, savedOptionGroupSchema, savedOptionSetCompositionSchema, savedOptionSetFromProductRequestSchema, savedOptionSetFromProductResultSchema, savedOptionSetListQuerySchema, savedOptionSetRequestSchema, savedOptionSetSchema, savedOptionSetSortSchema, savedOptionValueRequestSchema, savedOptionValueSchema, scopeAccessSchema, searchStorefrontFilesRequestSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, setStorefrontVisibilityRequestSchema, settleCouponShortfall, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeSubscriptionSchema, storefrontBuildDependenciesSchema, storefrontBuildListQuerySchema, storefrontBuildSchema, storefrontBuildStatusSchema, storefrontCheckSchema, storefrontCheckStatusSchema, storefrontCustomDomainStatusSchema, storefrontCustomHostnameProblem, storefrontDependencyFindingSchema, storefrontDeploymentLogSchema, storefrontDeploymentSchema, storefrontDeploymentStepSchema, storefrontDnsRecordSchema, storefrontDomainSchema, storefrontDomainTxtNameOf, storefrontEditPreviewLabelOf, storefrontEditPreviewSchema, storefrontEditSessionSchema, storefrontEditSessionStatusSchema, storefrontEditingSchema, storefrontFileConflictDetailsSchema, storefrontFileContentQuerySchema, storefrontFileContentSchema, storefrontFileDeleteResultSchema, storefrontFileEncodingSchema, storefrontFileEntrySchema, storefrontFileHashSchema, storefrontFileListQuerySchema, storefrontFileListSchema, storefrontFileMoveResultSchema, storefrontFilePathSchema, storefrontFileSearchResultSchema, storefrontFileWriteResultSchema, storefrontHostingSchema, storefrontPreviewLinkSchema, storefrontProvisioningSchema, storefrontRuleResultSchema, storefrontRuleSeveritySchema, storefrontSiteDomainSchema, storefrontSiteDomainsSchema, storefrontSiteSchema, storefrontSiteStatusSchema, storefrontSlugAvailabilityQuerySchema, storefrontSlugAvailabilitySchema, storefrontSlugSchema, storefrontSourceArchivePartSchema, storefrontSourceArchiveQuerySchema, storefrontSourceBlobsResultSchema, storefrontSourceModeSchema, storefrontSourceRefSchema, storefrontSourceReplacedSchema, storefrontSourceSchema, storefrontSuspensionSchema, storefrontTemplateSchema, storefrontVerifyReportSchema, storefrontVersionCreatedSchema, storefrontVersionSchema, storefrontVersionStatusSchema, storefrontVisibilitySchema, subscriptionLimitsSchema, subscriptionStatusSchema, subscriptionUsageSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateCouponRequestSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadStorefrontSourceBlobsRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema, writeStorefrontFilesRequestSchema };
+export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, BUSINESS_INFO_MAX_LENGTH, BUSINESS_NUMBER_PATTERN, CASH_RECEIPT_STATUS_VALUES, COLLECTION_PRODUCT_SORTS, COLLECTION_SLUG_PATTERN, COLLECTION_TYPES, COUPON_CODE_PATTERN, COUPON_CONDITIONS_DEFAULTS, COUPON_TARGET_ALL, COUPON_TARGET_LIST_MAX, CUSTOM_INPUT_FORBIDDEN_WORDS, FULFILLMENT_RULES, MAX_ADDON_GROUPS, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_COLLECTIONS, MAX_COLLECTION_DESCRIPTION, MAX_COLLECTION_PRODUCTS, MAX_COLLECTION_PRODUCTS_PER_ADD, MAX_COLLECTION_TITLE, MAX_CUSTOM_INPUTS, MAX_CUSTOM_INPUT_LENGTH, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_SAVED_OPTION_SETS, MAX_SAVED_OPTION_SET_NAME, 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, REFUND_POLICY_DEFAULTS, REFUND_POLICY_DELIVERY_FEE_KEYS, REMOTE_AREA_ZIP_RANGES, RESERVED_STOREFRONT_SLUGS, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STOREFRONT_BLOCKED_PATH_SEGMENTS, STOREFRONT_BUILD_STAGES, STOREFRONT_BUILD_TERMINAL_STATUSES, STOREFRONT_CHECK_TERMINAL_STATUSES, STOREFRONT_CUSTOM_DOMAIN_LIMIT_DEFAULT, STOREFRONT_DOMAIN_DNS_GRACE_DAYS, STOREFRONT_DOMAIN_DNS_WAIT_DAYS, STOREFRONT_DOMAIN_TXT_LABEL, STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES, STOREFRONT_EDIT_CAPACITY, STOREFRONT_EDIT_IDLE_MINUTES, STOREFRONT_EDIT_PREVIEW_SUFFIX, STOREFRONT_EDIT_START_STAGES, STOREFRONT_FILE_BATCH_MAX, STOREFRONT_FILE_MAX_BYTES, STOREFRONT_PATH_SEGMENT_PATTERN, STOREFRONT_PLATFORM_DOMAINS, STOREFRONT_PUBLIC_SUFFIXES, STOREFRONT_SEARCH_REGEX_MAX_LENGTH, STOREFRONT_SHOWCASE_SLUG_PREFIX, STOREFRONT_SITE_CREATE_LIMIT, STOREFRONT_SLUG_CHANGE_LIMIT, STOREFRONT_SLUG_CHANGE_WINDOW_DAYS, STOREFRONT_SLUG_HOLD_DAYS, STOREFRONT_SLUG_PATTERN, STOREFRONT_SOURCE_BLOB_BATCH_MAX, STOREFRONT_SOURCE_PART_BYTES, STOREFRONT_WORKSPACE_MAX_BYTES, STOREFRONT_WORKSPACE_MAX_FILES, 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_COUNT_WARNING, 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, addStorefrontDomainRequestSchema, addonGroupRequestSchema, addonGroupSchema, addonValueRequestSchema, addonValueSchema, 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, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, businessInfoPatchShape, businessInfoResponseShape, businessNumberSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeStorefrontSlugRequestSchema, changeStorefrontTemplateRequestSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, collectionCreateRequestSchema, collectionListQuerySchema, collectionPageSchema, collectionPatchRequestSchema, collectionProductListQuerySchema, collectionProductSchema, collectionProductSortRequestSchema, collectionProductsAddRequestSchema, collectionProductsReplaceRequestSchema, collectionSchema, collectionStateCountsSchema, collectionStateOf, collectionStateSchema, 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, createStorefrontEditPreviewLinkRequestSchema, createStorefrontPreviewLinkRequestSchema, createStorefrontSiteRequestSchema, createStorefrontVersionRequestSchema, customInputLabelForbiddenWord, customInputRequestSchema, customInputSchema, customInputValueSchema, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerCouponSchema, customerDelegationRequestSchema, customerDelegationSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deleteStorefrontFileRequestSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, disableStorefrontHostingRequestSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, fulfillBulkRequestSchema, fulfillRequestSchema, fulfillmentRuleOf, fulfillmentTypeOf, fulfillmentTypeResponseSchema, fulfillmentTypeSchema, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isCouponTargetLine, isEditableStorefrontPath, isReservedStoreCode, isReservedStorefrontSlug, isShowcaseStorefrontSlug, isStoreScope, isWebOrigin, issueCouponRequestSchema, issueCouponResultSchema, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, mcpRuleResultSchema, mcpToolEventSchema, moveStorefrontFileRequestSchema, myAccountSchema, myStoreSchema, normalizeBusinessNumber, normalizeCouponCode, normalizeStorefrontHostname, normalizeStorefrontPath, oauthTokenResponseSchema, openFulfillmentUnion, optionGroupKindSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionSelectionSchema, optionSortSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderDiscountSchema, orderFulfilledWebhookEventDataSchema, orderFulfilledWebhookEventSchema, orderItemFulfillmentSchema, orderItemFulfillmentSnapshotResponseSchema, orderItemFulfillmentSnapshotSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentFailureWarningSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, planCodeSchema, planEntitlementsSchema, planErrorDetailsSchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productFulfillmentCreateSchema, productFulfillmentResponseSchema, productFulfillmentSchema, productFulfillmentUpdateSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productRefundPolicyPatchSchema, productReplaceRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedPaidRefundBase, proratedRefundBase, publicPlanSchema, publicPlansSchema, publishStorefrontVersionRequestSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, quoteDelivery, quotePricing, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, replaceStorefrontSourceRequestSchema, requiresCollection, requiresShipping, resolveRefundPolicy, resolveShippingPolicy, responsePlanCodeSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, rollbackStorefrontRequestSchema, runStorefrontCheckRequestSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, savedCustomInputRequestSchema, savedCustomInputSchema, savedOptionGroupRequestSchema, savedOptionGroupSchema, savedOptionSetCompositionSchema, savedOptionSetFromProductRequestSchema, savedOptionSetFromProductResultSchema, savedOptionSetListQuerySchema, savedOptionSetRequestSchema, savedOptionSetSchema, savedOptionSetSortSchema, savedOptionValueRequestSchema, savedOptionValueSchema, scopeAccessSchema, searchStorefrontFilesRequestSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, setStorefrontVisibilityRequestSchema, settleCouponShortfall, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeSubscriptionSchema, storefrontBuildDependenciesSchema, storefrontBuildListQuerySchema, storefrontBuildSchema, storefrontBuildStatusSchema, storefrontCheckSchema, storefrontCheckStatusSchema, storefrontCustomDomainStatusSchema, storefrontCustomHostnameProblem, storefrontDependencyFindingSchema, storefrontDeploymentLogSchema, storefrontDeploymentSchema, storefrontDeploymentStepSchema, storefrontDnsRecordSchema, storefrontDomainSchema, storefrontDomainTxtNameOf, storefrontEditPreviewLabelOf, storefrontEditPreviewSchema, storefrontEditSessionSchema, storefrontEditSessionStatusSchema, storefrontEditingSchema, storefrontFileConflictDetailsSchema, storefrontFileContentQuerySchema, storefrontFileContentSchema, storefrontFileDeleteResultSchema, storefrontFileEncodingSchema, storefrontFileEntrySchema, storefrontFileHashSchema, storefrontFileListQuerySchema, storefrontFileListSchema, storefrontFileMoveResultSchema, storefrontFilePathSchema, storefrontFileSearchResultSchema, storefrontFileWriteResultSchema, storefrontHostingSchema, storefrontPreviewLinkSchema, storefrontProvisioningSchema, storefrontRuleResultSchema, storefrontRuleSeveritySchema, storefrontSiteDomainSchema, storefrontSiteDomainsSchema, storefrontSiteSchema, storefrontSiteStatusSchema, storefrontSlugAvailabilityQuerySchema, storefrontSlugAvailabilitySchema, storefrontSlugSchema, storefrontSourceArchivePartSchema, storefrontSourceArchiveQuerySchema, storefrontSourceBlobsResultSchema, storefrontSourceModeSchema, storefrontSourceRefSchema, storefrontSourceReplacedSchema, storefrontSourceSchema, storefrontSuspensionSchema, storefrontTemplateSchema, storefrontVerifyReportSchema, storefrontVersionCreatedSchema, storefrontVersionSchema, storefrontVersionStatusSchema, storefrontVisibilitySchema, subscriptionLimitsSchema, subscriptionStatusSchema, subscriptionUsageSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateCouponRequestSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadStorefrontSourceBlobsRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema, writeStorefrontFilesRequestSchema };