@sayren/store-sdk 0.8.0 → 0.10.0

package/src/client.ts

@@ -1,6 +1,14 @@
 import { z } from "zod";
 import { base64Utf8 } from "./base64";
-import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
+import {
+  ApiError,
+  createHttp,
+  path,
+  type Query,
+  resolveToken,
+  type TokenSource,
+  unwrapData,
+} from "./http";
 import {
   type AnalyticsPagesParams,
   type AnalyticsProductsParams,
@@ -62,6 +70,8 @@ import {
 } from "./schemas/claim";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
+  type ConsentKind,
+  customerConsentSchema,
   customerDetailSchema,
   type customerListQuerySchema,
   customerOrderSchema,
@@ -173,7 +183,14 @@ import {
   type UpdateStoreRequest,
   updateStoreRequestSchema,
 } from "./schemas/store";
-import { type UploadRequest, uploadRequestSchema, uploadTicketSchema } from "./schemas/upload";
+import {
+  type UploadPurpose,
+  type UploadRequest,
+  type UploadTicket,
+  uploadRejection,
+  uploadRequestSchema,
+  uploadTicketSchema,
+} from "./schemas/upload";
 import type { AuthorizeOptions, StoreSession } from "./session";
 
 export interface StoreClientOptions {
@@ -372,6 +389,44 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("POST", "/uploads", uploadTicketSchema, {
           body: uploadRequestSchema.parse(body),
         }),
+      /**
+       * 자리 발급 + 바이트 PUT을 한 번에 — 끝나면 `url`이 공개 주소다.
+       *
+       * 용도 제한(확장자·크기)은 서버가 판정하지만, 같은 규칙으로 여기서 먼저 걸러
+       * 큰 파일을 CDN까지 보내고 나서 거절되는 왕복을 없앤다.
+       */
+      upload: async (
+        file: Blob,
+        options?: { purpose?: UploadPurpose; filename?: string },
+      ): Promise<UploadTicket> => {
+        const filename =
+          options?.filename ??
+          (typeof File !== "undefined" && file instanceof File ? file.name : "");
+        if (!filename) {
+          throw new ApiError(400, "UPLOAD_FILENAME_REQUIRED", "파일명이 필요합니다");
+        }
+        if (file.size === 0) {
+          // 빈 파일은 PUT 자체는 성공하고 0바이트 객체가 공개돼 깨진 이미지로 남는다
+          throw new ApiError(400, "EMPTY_FILE", `파일이 비어 있습니다: ${filename}`);
+        }
+        const purpose = options?.purpose ?? "description";
+        const rejection = uploadRejection(purpose, filename, file.size);
+        if (rejection) {
+          throw new ApiError(rejection.status, rejection.code, rejection.message);
+        }
+        const ticket = await storeHttp.request("POST", "/uploads", uploadTicketSchema, {
+          body: uploadRequestSchema.parse({ filename, purpose, size: file.size }),
+        });
+        const put = await fetchFn(ticket.uploadUrl, {
+          method: "PUT",
+          headers: { "content-type": file.type || "application/octet-stream" },
+          body: file,
+        });
+        if (!put.ok) {
+          throw new ApiError(put.status, "UPLOAD_PUT_FAILED", `업로드에 실패했습니다: ${filename}`);
+        }
+        return ticket;
+      },
     },
 
     products: {
@@ -532,6 +587,20 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/dispatch/tracking`, {
           body: { carrierCode, trackingNumber },
         }),
+      /**
+       * 배송완료 처리 — `DISPATCHED`·`DELIVERING`만 넘어간다. 응답의 `autoDecisionDate`가 자동 구매확정 예정일이다
+       * (스토어 설정 `autoConfirmDays`가 0이면 null).
+       */
+      markDelivered: (orderItemId: string, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/order-items/${orderItemId}/delivered`, orderItemSchema, {
+          headers: idempotency(idempotencyKey),
+        }),
+      /** 배송완료 일괄 처리 — 항목별 부분 성공이다 */
+      markDeliveredBulk: (orderItemIds: string[], idempotencyKey?: string) =>
+        storeHttp.request("POST", "/order-items/delivered", bulkResultSchema, {
+          body: { orderItemIds },
+          headers: idempotency(idempotencyKey),
+        }),
       getDelivery: (orderItemId: string) =>
         storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
     },
@@ -641,6 +710,14 @@ export function createStoreClient(options: StoreClientOptions) {
             query: params as Query,
           },
         ),
+      /** 동의 이력 — 최근 순. 가입·재동의·마케팅 변경이 한 줄씩 남는다 */
+      consents: (customerId: string, params?: PageParams & { kind?: ConsentKind }) =>
+        storeHttp.request(
+          "GET",
+          path`/customers/${customerId}/consents`,
+          pageSchema(customerConsentSchema),
+          { query: params as Query },
+        ),
       withdraw: (customerId: string, body: WithdrawCustomerRequest) =>
         storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, {
           body: withdrawCustomerRequestSchema.parse(body),

package/src/index.ts

@@ -24,6 +24,7 @@ export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";
 export * from "./schemas/product";
+export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
 export * from "./schemas/store";
 export * from "./schemas/upload";

package/src/schemas/claim.ts

@@ -41,8 +41,24 @@ export const claimSchema = z.object({
   reason: claimReasonSchema,
   reasonDetail: z.string().nullable(),
   responsibility: z.enum(["BUYER", "SELLER"]),
-  claimDeliveryFee: z.number().int(),
-  expectedRefundAmount: z.number().int().nullable(),
+  claimDeliveryFee: z.number().int().describe("구매자가 부담하는 반품·교환 배송비. 원 단위"),
+  expectedRefundAmount: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "접수 시점에 계산한 예상 환불액 — 수량 비율 상품 금액 − 반품 배송비 − 조건부 무료배송 미달 차감. " +
+        "**배송비 환불은 포함되지 않고 `expectedDeliveryFeeRefundAmount`로 따로 온다**" +
+        "(승인 시점의 배송 묶음 상태로 확정되기 때문이다). 교환은 환불이 없어 null이다",
+    ),
+  expectedDeliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "접수 시점에 계산한 예상 배송비 환불액. 배송 묶음(같은 상품의 주문상품)이 모두 취소되거나 " +
+        "판매자 귀책일 때만 0보다 크다. 이 필드가 생기기 전에 접수된 클레임은 null이다",
+    ),
   exchangeOption: z.object({ optionId: z.string(), optionName: z.string() }).nullable(),
   collect: z
     .object({
@@ -119,8 +135,26 @@ export type RejectClaimRequest = z.infer<typeof rejectClaimRequestSchema>;
 
 export const approveClaimResultSchema = z.object({
   claimId: z.string(),
-  refundAmount: z.number().int(),
-  deductAmount: z.number().int(),
+  refundAmount: z
+    .number()
+    .int()
+    .describe(
+      "실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − " +
+        "추가 차감(`deductAmount`)",
+    ),
+  deductAmount: z.number().int().describe("승인 때 셀러가 추가로 차감한 금액"),
+  quantity: z.number().int().describe("환불한 수량"),
+  deliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .describe("환불에 포함된 배송비. 배송 묶음 전량 취소나 판매자 귀책일 때만 0보다 크다"),
+  deliveryFeeChargeAmount: z
+    .number()
+    .int()
+    .describe(
+      "환불액에서 뺀 **배송비** — 반품·교환 배송비 + 조건부 무료배송 미달 차감. " +
+        "추가 차감(`deductAmount`)은 포함하지 않는다",
+    ),
   refundedAt: z.string(),
 });
 

package/src/schemas/common.ts

@@ -67,6 +67,9 @@ export const changeTypeSchema = z.enum([
   "CLAIM.CANCEL_REQUESTED",
   "CLAIM.RETURN_REQUESTED",
   "CLAIM.EXCHANGE_REQUESTED",
+  // 취소·반품 승인으로 주문상품이 취소됐다 — 서버가 이 값을 쓰므로 목록에 있어야 한다
+  // (빠져 있던 동안 클레임이 끝난 주문상품이 섞이면 응답 검증이 깨졌다)
+  "CLAIM.COMPLETED",
   "ORDER.ADDRESS_CHANGE_REQUESTED",
 ]);
 

package/src/schemas/customer.ts

@@ -58,6 +58,75 @@ export const customerAddressSchema = z.object({
   address2: z.string().nullable(),
 });
 
+// ── 동의 이력 (이슈 #26) ────────────────────────────────────
+
+/** 동의 종류 — 이용약관·개인정보 수집이용은 가입 필수, 마케팅 수신은 선택 */
+export const consentKindSchema = z.enum(["TERMS", "PRIVACY", "MARKETING"]);
+export type ConsentKind = z.infer<typeof consentKindSchema>;
+
+export const consentActionSchema = z.enum(["AGREED", "WITHDRAWN"]);
+export type ConsentAction = z.infer<typeof consentActionSchema>;
+
+/**
+ * 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
+ * `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
+ * `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
+ */
+export const consentSourceSchema = z.enum([
+  "SIGNUP",
+  "SOCIAL_SIGNUP",
+  "DELEGATED",
+  "RECONSENT",
+  "MEMBER_UPDATE",
+  "SELLER",
+]);
+export type ConsentSource = z.infer<typeof consentSourceSchema>;
+
+/** 동의 이력 한 줄 — 추가만 되고 지워지지 않는다(구매자 탈퇴 시에만 함께 지워진다) */
+export 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(),
+});
+export type CustomerConsent = z.infer<typeof customerConsentSchema>;
+
+/** 종류별 현재 동의 상태 */
+export 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(),
+});
+export type CustomerConsentState = z.infer<typeof customerConsentStateSchema>;
+
+export const customerConsentsSchema = z.object({
+  terms: customerConsentStateSchema,
+  privacy: customerConsentStateSchema,
+  marketing: customerConsentStateSchema,
+  /** 필수 동의 중 하나라도 현재 버전이 아니면 true */
+  reconsentRequired: z.boolean(),
+});
+export type CustomerConsents = z.infer<typeof customerConsentsSchema>;
+
+/** `GET /v1/customers/{id}/consents` 쿼리 — 최근 순이다 */
+export const customerConsentListQuerySchema = z.object({
+  kind: consentKindSchema.optional().describe("동의 종류 필터. 생략하면 전체"),
+  ...pageQueryShape(),
+});
+
 /** 구매자 상세 — 휴대폰 전체를 보여 준다 */
 export const customerDetailSchema = z.object({
   customerId: z.string(),
@@ -76,6 +145,9 @@ export const customerDetailSchema = z.object({
       }),
     )
     .describe("로그인 방법 — 이메일·비밀번호(`password`)와 연결된 소셜 계정"),
+  consents: customerConsentsSchema.describe(
+    "약관·개인정보·마케팅 동의의 현재 상태. 이력은 `GET /v1/customers/{customerId}/consents`",
+  ),
   addresses: z.array(customerAddressSchema),
   stats: customerStatsSchema.extend({
     canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),

package/src/schemas/order.ts

@@ -40,10 +40,18 @@ export const orderItemSchema = z.object({
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
   sellerCode: z.string().nullable(),
-  quantity: z.number().int(),
+  quantity: z.number().int().describe("주문 수량"),
+  canceledQuantity: z
+    .number()
+    .int()
+    .describe("취소·반품으로 환불된 누적 수량. 수량 단위 부분 취소가 없었으면 0이다"),
+  activeQuantity: z
+    .number()
+    .int()
+    .describe("살아 있는 수량 (`quantity` − `canceledQuantity`). 0이면 주문상품이 전량 취소됐다"),
   unitPrice: z.number().int(),
   discountAmount: z.number().int(),
-  totalPrice: z.number().int(),
+  totalPrice: z.number().int().describe("주문상품 금액 (할인 반영 단가 × 주문 수량)"),
   hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
   autoDecisionDate: z.string().nullable(),
   sellerMemo: z.string().nullable(),
@@ -256,6 +264,15 @@ export type HoldOrderItemRequest = z.infer<typeof holdOrderItemRequestSchema>;
 export const cancelBySellerRequestSchema = z.object({
   reason: z.enum(["OUT_OF_STOCK", "PRICE_ERROR", "DELIVERY_IMPOSSIBLE", "ETC"]),
   detail: z.string().max(500).optional(),
+  quantity: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe(
+      "취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. " +
+        "일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다",
+    ),
 });
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
@@ -263,7 +280,22 @@ export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 export const cancelBySellerResultSchema = z.object({
   orderItemId: z.string(),
-  refundAmount: z.number().int(),
+  refundAmount: z
+    .number()
+    .int()
+    .describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감"),
+  quantity: z.number().int().describe("취소한 수량"),
+  canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
+  deliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .describe(
+      "환불에 포함된 배송비. 배송 묶음(같은 상품)이 모두 취소됐고 환불 정책이 켜져 있을 때만 0보다 크다",
+    ),
+  deliveryFeeChargeAmount: z
+    .number()
+    .int()
+    .describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
   refundedAt: z.string(),
 });
 

package/src/schemas/product.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
+import { refundPolicyPatchSchema } from "./refund-policy";
+import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
 
@@ -89,6 +91,10 @@ export const productSchema = productSummarySchema.extend({
   conditionalFreeAmount: z.number().int().nullable().optional(),
   returnFee: z.number().int().optional(),
   exchangeFee: z.number().int().optional(),
+  refundPolicy: refundPolicyPatchSchema
+    .nullable()
+    .optional()
+    .describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
   shippingAddressId: z.string().nullable().optional(),
   returnAddressId: z.string().nullable().optional(),
   createdAt: z.string().optional(),
@@ -96,6 +102,62 @@ export const productSchema = productSummarySchema.extend({
 
 export type Product = z.infer<typeof productSchema>;
 
+/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
+export const MAX_PRODUCT_IMAGES = 10;
+
+/**
+ * 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
+ *
+ * https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
+ * **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
+ * 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
+ *
+ * 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
+ * 만들면 상품 조회 자체가 막힌다.
+ */
+export const productImageUrlSchema = z
+  .url()
+  .max(2048)
+  .describe("상품 이미지 주소. https만 허용하고, 확장자가 있으면 이미지 형식이어야 한다");
+
+export interface ProductImageRejection {
+  code: "INVALID_IMAGE_URL" | "UNSUPPORTED_FILE_TYPE";
+  message: string;
+}
+
+/**
+ * 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
+ *
+ * - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
+ *   상세 화면에 박히는 주입 경로가 된다.
+ * - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
+ * - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
+ *   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+ */
+export function productImageRejection(url: string): ProductImageRejection | null {
+  if (url.length > 2048) {
+    return { code: "INVALID_IMAGE_URL", message: "이미지 주소가 너무 깁니다" };
+  }
+  let parsed: URL;
+  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;
+}
+
 /** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
 export const MAX_OPTION_GROUPS = 3;
 /** 축 하나가 가질 수 있는 값의 최대 개수 */
@@ -212,7 +274,12 @@ export const productCreateRequestSchema = z
      * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
      */
     descriptionJson: z.string().nullable().optional(),
-    images: z.array(z.url()).min(1).max(10).optional(),
+    images: z
+      .array(productImageUrlSchema)
+      .min(1)
+      .max(MAX_PRODUCT_IMAGES)
+      .optional()
+      .describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
     attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
     deliveryType: deliveryTypeSchema
       .default("PAID")
@@ -223,8 +290,22 @@ export const productCreateRequestSchema = z
       .int()
       .optional()
       .describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
-    returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위"),
-    exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위"),
+    returnFee: z
+      .number()
+      .int()
+      .default(0)
+      .describe("반품 배송비. 원 단위. `refundPolicy.returnDeliveryFee`와 같은 값이다"),
+    exchangeFee: z
+      .number()
+      .int()
+      .default(0)
+      .describe("교환 배송비. 원 단위. `refundPolicy.exchangeDeliveryFee`와 같은 값이다"),
+    refundPolicy: refundPolicyPatchSchema
+      .nullish()
+      .describe(
+        "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
+          "`returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다",
+      ),
     shippingAddressId: z.string().optional(),
     returnAddressId: z.string().optional(),
   })
@@ -276,13 +357,6 @@ export const productListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
-/** `POST /v1/product-images` 응답 — 업로드된 이미지의 CDN 주소 */
-export const productImageUploadResultSchema = z.object({
-  images: z.array(z.object({ url: z.url(), width: z.number().int(), height: z.number().int() })),
-});
-
-export type ProductImageUploadResult = z.infer<typeof productImageUploadResultSchema>;
-
 export const discountSchema = z.object({
   productId: z.string(),
   discountType: z.enum(["RATE", "AMOUNT"]),

package/src/schemas/refund-policy.ts

@@ -0,0 +1,163 @@
+import { z } from "zod";
+
+/**
+ * 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
+ *
+ * 두 층이다. 스토어 설정(`PATCH /v1/store`의 `refundPolicy`)이 기본값이고, 상품별 정책
+ * (`POST/PUT /v1/products`의 `refundPolicy`)이 그 상품에만 덮어쓴다. 상품이 정하지 않은 항목은
+ * 스토어 기본을 따르고, 스토어도 정하지 않았으면 `REFUND_POLICY_DEFAULTS`다.
+ *
+ * 한 주문에 정책이 섞이면 **상품별로 계산한다**. 배송비 묶음도 상품 단위다(주문서·장바구니의
+ * 배송비 합산과 같은 규칙: 같은 상품의 주문상품이 한 묶음이고 묶음마다 배송비가 붙는다).
+ */
+
+const descriptions = {
+  preShipmentDeliveryFeeRefund:
+    "발송 전 취소로 배송 묶음(같은 상품의 주문상품)이 모두 취소되면 그 묶음의 배송비를 환불한다. " +
+    "false면 배송비를 환불하지 않는다. 기본 true",
+  returnDeliveryFee:
+    "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). " +
+    "상품별 정책에서 이 값을 주면 상품의 `returnFee`도 같은 값으로 맞춘다",
+  exchangeDeliveryFee:
+    "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). " +
+    "상품별 정책에서 이 값을 주면 상품의 `exchangeFee`도 같은 값으로 맞춘다",
+  sellerFaultFreeShipping:
+    "판매자 귀책(셀러 직권취소, 불량·오배송 반품)이면 배송비를 셀러가 부담한다 — 배송비를 환불하고 반품비를 받지 않는다. " +
+    "false면 구매자 귀책과 같은 규칙을 쓴다. 기본 true",
+  conditionalFreeShortfallCharge:
+    "조건부 무료배송(`CONDITIONAL_FREE`) 상품에서 일부 취소로 남은 금액이 무료 기준액에 미달하면 그 배송비를 환불액에서 뺀다. " +
+    "false면 추가 청구 없이 셀러가 부담한다. 기본 false",
+} as const;
+
+/** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
+export const refundPolicySchema = z.object({
+  preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions.preShipmentDeliveryFeeRefund),
+  returnDeliveryFee: z.number().int().min(0).describe(descriptions.returnDeliveryFee),
+  exchangeDeliveryFee: z.number().int().min(0).describe(descriptions.exchangeDeliveryFee),
+  sellerFaultFreeShipping: z.boolean().describe(descriptions.sellerFaultFreeShipping),
+  conditionalFreeShortfallCharge: z.boolean().describe(descriptions.conditionalFreeShortfallCharge),
+});
+
+export type RefundPolicy = z.infer<typeof refundPolicySchema>;
+
+/**
+ * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ *
+ * `as const`가 아니라 `RefundPolicy`로 타입을 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
+ * `true` 자리에 `false`를 넣을 수 없다.
+ */
+export const REFUND_POLICY_DEFAULTS: RefundPolicy = {
+  preShipmentDeliveryFeeRefund: true,
+  returnDeliveryFee: 0,
+  exchangeDeliveryFee: 0,
+  sellerFaultFreeShipping: true,
+  conditionalFreeShortfallCharge: false,
+};
+
+/**
+ * 부분 정책 — 스토어 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
+ *
+ * `strictObject`라 모르는 키는 400이다. 오타(`returnFee` 등)를 조용히 무시하면 셀러는 저장됐다고
+ * 믿는데 정책은 기본값으로 남는다.
+ */
+export const refundPolicyPatchSchema = z.strictObject({
+  preShipmentDeliveryFeeRefund: z
+    .boolean()
+    .optional()
+    .describe(descriptions.preShipmentDeliveryFeeRefund),
+  returnDeliveryFee: z.number().int().min(0).optional().describe(descriptions.returnDeliveryFee),
+  exchangeDeliveryFee: z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe(descriptions.exchangeDeliveryFee),
+  sellerFaultFreeShipping: z.boolean().optional().describe(descriptions.sellerFaultFreeShipping),
+  conditionalFreeShortfallCharge: z
+    .boolean()
+    .optional()
+    .describe(descriptions.conditionalFreeShortfallCharge),
+});
+
+export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
+
+/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기와 레거시 배송비 필드 */
+export interface RefundPolicyProductInput {
+  /** 상품별 덮어쓰기. 없으면 스토어 기본을 그대로 쓴다 */
+  refundPolicy?: RefundPolicyPatch | null;
+  /** @deprecated 레거시 상품 반품비 — `refundPolicy`가 없는 옛 상품의 값이다 */
+  returnFee?: number | null;
+  /** @deprecated 레거시 상품 교환비 — `refundPolicy`가 없는 옛 상품의 값이다 */
+  exchangeFee?: number | null;
+}
+
+/**
+ * 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
+ *
+ * 반품비·교환비는 레거시 필드(`products.returnFee`·`exchangeFee`)와 **연결**한다. 상품이
+ * `refundPolicy.returnDeliveryFee`를 정하면 그 값이 원천이고(서버가 `returnFee`도 같은 값으로 맞춘다),
+ * 정하지 않았으면 레거시 값이 0보다 클 때 그 값을 쓴다. 0이면 스토어 기본을 따른다 —
+ * 정책이 생기기 전에 만든 상품(반품비 0)이 스토어 기본을 물려받게 하는 규칙이다.
+ */
+export function resolveRefundPolicy(
+  storePolicy?: RefundPolicyPatch | null,
+  product?: RefundPolicyProductInput | null,
+): RefundPolicy {
+  const store = { ...REFUND_POLICY_DEFAULTS, ...dropUndefined(storePolicy) };
+  return { ...store, ...(productRefundPolicyOverride(product) ?? {}) };
+}
+
+/**
+ * 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
+ *
+ * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
+ * 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
+ * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
+ */
+export function productRefundPolicyOverride(
+  product?: RefundPolicyProductInput | null,
+): RefundPolicyPatch | null {
+  const override = dropUndefined(product?.refundPolicy);
+  const legacy: RefundPolicyPatch = {};
+  if (override.returnDeliveryFee === undefined && (product?.returnFee ?? 0) > 0) {
+    legacy.returnDeliveryFee = product?.returnFee ?? 0;
+  }
+  if (override.exchangeDeliveryFee === undefined && (product?.exchangeFee ?? 0) > 0) {
+    legacy.exchangeDeliveryFee = product?.exchangeFee ?? 0;
+  }
+  const merged = { ...legacy, ...override };
+  if (product?.refundPolicy == null && Object.keys(merged).length === 0) return null;
+  return merged;
+}
+
+/** `undefined` 값을 빼고 얕게 복사한다 — 전개 순서로 덮어쓸 때 `undefined`가 기본값을 지우지 않게 */
+function dropUndefined(patch?: RefundPolicyPatch | null): RefundPolicyPatch {
+  if (!patch) return {};
+  return Object.fromEntries(
+    Object.entries(patch).filter(([, value]) => value !== undefined),
+  ) as RefundPolicyPatch;
+}
+
+/**
+ * 수량 단위 부분 취소의 환불 기준액 — **누적 내림의 차분**이다.
+ *
+ * 원 단위 반올림 규칙: `floor(주문상품 금액 × 누적 수량 ÷ 전체 수량)`을 두 번 구해 그 차를 쓴다.
+ * 부분 취소를 몇 번 나눠도 합이 주문상품 금액과 정확히 같아서 1원이 남거나 넘치지 않는다.
+ * 할인은 이미 단가에 들어 있어(주문 단위 쿠폰이 없다) 별도 안분이 없다.
+ *
+ * @param totalPrice 주문상품 금액 (할인 반영 단가 × 전체 수량)
+ * @param quantity 주문상품 전체 수량
+ * @param settledQuantity 이미 취소·반품된 누적 수량
+ * @param cancelQuantity 이번에 취소·반품할 수량
+ */
+export function proratedRefundBase(
+  totalPrice: number,
+  quantity: number,
+  settledQuantity: number,
+  cancelQuantity: number,
+): number {
+  if (quantity <= 0 || cancelQuantity <= 0) return 0;
+  const before = Math.floor((totalPrice * settledQuantity) / quantity);
+  const after = Math.floor((totalPrice * (settledQuantity + cancelQuantity)) / quantity);
+  return Math.max(0, after - before);
+}