@sayren/store-sdk 0.16.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -78,6 +78,21 @@ import {
   rejectClaimRequestSchema,
 } from "./schemas/claim";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
+import {
+  type CreateCouponRequest,
+  couponIssueSchema,
+  type couponListQuerySchema,
+  couponRedemptionSchema,
+  couponSchema,
+  couponStatsSchema,
+  createCouponRequestSchema,
+  customerCouponSchema,
+  type IssueCouponRequest,
+  issueCouponRequestSchema,
+  issueCouponResultSchema,
+  type UpdateCouponRequest,
+  updateCouponRequestSchema,
+} from "./schemas/coupon";
 import {
   type ConsentKind,
   customerConsentSchema,
@@ -88,6 +103,21 @@ import {
   type WithdrawCustomerRequest,
   withdrawCustomerRequestSchema,
 } from "./schemas/customer";
+import {
+  type DigitalAssetAttachRequest,
+  digitalAssetAttachRequestSchema,
+  digitalAssetPreviewSchema,
+  digitalAssetSchema,
+} from "./schemas/digital-asset";
+import {
+  type FulfillmentCodeUploadRequest,
+  fulfillmentCodeBatchSchema,
+  type fulfillmentCodeListQuerySchema,
+  fulfillmentCodePageSchema,
+  fulfillmentCodeRevealSchema,
+  fulfillmentCodeSchema,
+  fulfillmentCodeUploadRequestSchema,
+} from "./schemas/fulfillment-code";
 import {
   type LoginProvider,
   loginProviderTestSchema,
@@ -128,6 +158,10 @@ import {
   deliveryInfoSchema,
   deliveryStatusSchema,
   dispatchRequestSchema,
+  type FulfillRequest,
+  fulfillBulkRequestSchema,
+  fulfillmentMailResendSchema,
+  fulfillRequestSchema,
   type HoldOrderItemRequest,
   holdOrderItemRequestSchema,
   type OrderItemListParams,
@@ -170,12 +204,14 @@ import {
   type OptionModelRequest,
   optionModelRequestSchema,
   optionModelSchema,
-  type ProductCreateRequest,
+  type ProductCreateRequestInput,
   type ProductListParams,
   type ProductPatchRequest,
+  type ProductReplaceRequestInput,
   type ProductStatus,
   productCreateRequestSchema,
   productPatchRequestSchema,
+  productReplaceRequestSchema,
   productSchema,
   productStatusSchema,
   productSummarySchema,
@@ -436,7 +472,8 @@ export function createStoreClient(options: StoreClientOptions) {
         });
         const put = await fetchFn(ticket.uploadUrl, {
           method: "PUT",
-          headers: { "content-type": file.type || "application/octet-stream" },
+          // 발급 응답의 헤더를 함께 싣는다 — 판매 파일(이슈 #48)은 비공개 헤더가 빠지면 공개 객체가 된다
+          headers: { ...ticket.headers, "content-type": file.type || "application/octet-stream" },
           body: file,
         });
         if (!put.ok) {
@@ -453,14 +490,14 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       get: (productId: string) =>
         storeHttp.request("GET", path`/products/${productId}`, productSchema),
-      create: (body: ProductCreateRequest, idempotencyKey?: string) =>
+      create: (body: ProductCreateRequestInput, idempotencyKey?: string) =>
         storeHttp.request("POST", "/products", productSchema, {
           body: productCreateRequestSchema.parse(body),
           headers: idempotency(idempotencyKey),
         }),
-      update: (productId: string, body: ProductCreateRequest) =>
+      update: (productId: string, body: ProductReplaceRequestInput) =>
         storeHttp.request("PUT", path`/products/${productId}`, productSchema, {
-          body: productCreateRequestSchema.parse(body),
+          body: productReplaceRequestSchema.parse(body),
         }),
       patch: (productId: string, body: ProductPatchRequest) =>
         storeHttp.requestVoid("PATCH", path`/products/${productId}`, {
@@ -499,6 +536,76 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       removeDiscount: (productId: string) =>
         storeHttp.requestVoid("DELETE", path`/products/${productId}/discount`),
+      /**
+       * 코드 일괄 업로드 (이슈 #48) — 코드 발급·자동 제공 상품의 코드 풀에 올린다. `codes`와 `csv` 중 하나만 보낸다.
+       * 받은 코드 수만큼 재고가 는다. 에러: 409 `NOT_CODE_PRODUCT`·`CODE_POOL_NOT_USED`·`CODE_UPLOAD_CONFLICT`, 400 `TOO_MANY_CODES`
+       */
+      uploadCodes: (
+        productId: string,
+        body: FulfillmentCodeUploadRequest,
+        idempotencyKey?: string,
+      ) =>
+        storeHttp.request("POST", path`/products/${productId}/codes`, fulfillmentCodeBatchSchema, {
+          body: fulfillmentCodeUploadRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      /** 코드 목록 — 가린 값(`hint`)만 싣는다. `available`은 필터와 무관한 판매 가능 코드 수다 */
+      listCodes: (
+        productId: string,
+        params?: PageParams & Omit<z.input<typeof fulfillmentCodeListQuerySchema>, "page" | "size">,
+      ) =>
+        storeHttp.request("GET", path`/products/${productId}/codes`, fulfillmentCodePageSchema, {
+          query: params as Query,
+        }),
+      /** 판매 가능 코드 폐기 — 재고가 1 준다. 배정된 코드는 409 `CODE_NOT_AVAILABLE` */
+      voidCode: (productId: string, codeId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/products/${productId}/codes/${codeId}/void`,
+          fulfillmentCodeSchema,
+        ),
+      /**
+       * 판매 파일 연결 (이슈 #48) — `uploads.create({ purpose: "digital-asset" })`로 받은 `key`에 파일을 올린 뒤 연결한다.
+       * 이후 주문부터 이 파일을 준다. 에러: 400 `INVALID_ASSET_KEY`, 409 `NOT_DOWNLOAD_PRODUCT`·`ASSET_ALREADY_ATTACHED`
+       */
+      attachDigitalAsset: (productId: string, body: DigitalAssetAttachRequest) =>
+        storeHttp.request("POST", path`/products/${productId}/digital-assets`, digitalAssetSchema, {
+          body: digitalAssetAttachRequestSchema.parse(body),
+        }),
+      /** 판매 파일 목록 — 해제한 파일도 싣는다. 객체 키·주소는 없다 */
+      listDigitalAssets: (productId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/products/${productId}/digital-assets`,
+          z.array(digitalAssetSchema),
+        ),
+      /** 판매 파일 해제 — 새 주문에 주지 않는다. 이미 산 구매자는 계속 받는다 */
+      removeDigitalAsset: (productId: string, assetId: string) =>
+        storeHttp.request(
+          "DELETE",
+          path`/products/${productId}/digital-assets/${assetId}`,
+          digitalAssetSchema,
+        ),
+      /** 판매 파일 확인 주소 — 수명 300초의 서명 주소 */
+      previewDigitalAsset: (productId: string, assetId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/products/${productId}/digital-assets/${assetId}/preview-url`,
+          digitalAssetPreviewSchema,
+        ),
+    },
+
+    fulfillmentCodes: {
+      /**
+       * 코드 평문 열람 — 콘솔에서 로그인한 OWNER·ADMIN만 된다(403 `INSUFFICIENT_ROLE`). 열람 기록과 감사 로그가 남는다.
+       * 평문은 화면에 보인 뒤 저장하지 않는다
+       */
+      reveal: (codeId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/fulfillment-codes/${codeId}/reveal`,
+          fulfillmentCodeRevealSchema,
+        ),
     },
 
     categories: {
@@ -624,6 +731,31 @@ export function createStoreClient(options: StoreClientOptions) {
           body: { orderItemIds },
           headers: idempotency(idempotencyKey),
         }),
+      /**
+       * 제공 안내 메일 재발송 (이슈 #48) — 제공된 주문상품의 안내 메일을 다시 보낸다. 주문상품당 하루 3회(429).
+       * 코드·파일 주소는 메일에 없다
+       */
+      resendFulfillmentMail: (orderItemId: string) =>
+        storeHttp.request(
+          "POST",
+          path`/order-items/${orderItemId}/fulfillment/mail`,
+          fulfillmentMailResendSchema,
+        ),
+      /**
+       * 제공 처리 (이슈 #48) — 수동 제공 비실물 주문상품(이용권·방문 수령)을 `PAID`·`CONFIRMED`에서 제공 완료(`DELIVERED`)로
+       * 바꾼다. `note`는 구매자 주문 상세에 이용 안내로 실린다. 배송 상품은 409 `SHIPPING_REQUIRED`
+       */
+      fulfill: (orderItemId: string, body: FulfillRequest = {}, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/order-items/${orderItemId}/fulfill`, orderItemSchema, {
+          body: fulfillRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      /** 제공 처리 일괄 — 항목별 부분 성공이다 */
+      fulfillBulk: (orderItemIds: string[], body: FulfillRequest = {}, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/order-items/fulfill", bulkResultSchema, {
+          body: fulfillBulkRequestSchema.parse({ orderItemIds, ...body }),
+          headers: idempotency(idempotencyKey),
+        }),
       getDelivery: (orderItemId: string) =>
         storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
     },
@@ -741,12 +873,69 @@ export function createStoreClient(options: StoreClientOptions) {
           pageSchema(customerConsentSchema),
           { query: params as Query },
         ),
+      /** 보유 쿠폰 (이슈 #47) — 최근 지급 순, 최대 500장 */
+      coupons: (customerId: string) =>
+        storeHttp.request(
+          "GET",
+          path`/customers/${customerId}/coupons`,
+          z.array(customerCouponSchema),
+        ),
       withdraw: (customerId: string, body: WithdrawCustomerRequest) =>
         storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, {
           body: withdrawCustomerRequestSchema.parse(body),
         }),
     },
 
+    /** 쿠폰 (이슈 #47) — 조회 `promotion:r`, 쓰기 `promotion:rw` */
+    coupons: {
+      list: (params?: PageParams & Omit<z.input<typeof couponListQuerySchema>, "page" | "size">) =>
+        storeHttp.request("GET", "/coupons", pageSchema(couponSchema), { query: params as Query }),
+      create: (body: CreateCouponRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", "/coupons", couponSchema, {
+          body: createCouponRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      get: (couponId: string) => storeHttp.request("GET", path`/coupons/${couponId}`, couponSchema),
+      update: (couponId: string, body: UpdateCouponRequest) =>
+        storeHttp.request("PATCH", path`/coupons/${couponId}`, couponSchema, {
+          body: updateCouponRequestSchema.parse(body),
+        }),
+      pause: (couponId: string) =>
+        storeHttp.request("POST", path`/coupons/${couponId}/pause`, couponSchema),
+      resume: (couponId: string) =>
+        storeHttp.request("POST", path`/coupons/${couponId}/resume`, couponSchema),
+      end: (couponId: string) =>
+        storeHttp.request("POST", path`/coupons/${couponId}/end`, couponSchema),
+      /** 셀러 지급 — 한 번에 1,000명까지. 한도에 걸린 구매자는 `failed`에 담긴다 */
+      issue: (couponId: string, body: IssueCouponRequest, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/coupons/${couponId}/issues`, issueCouponResultSchema, {
+          body: issueCouponRequestSchema.parse(body),
+          headers: idempotency(idempotencyKey),
+        }),
+      issues: (
+        couponId: string,
+        params?: PageParams & { status?: "AVAILABLE" | "RESERVED" | "USED" | "REVOKED" },
+      ) =>
+        storeHttp.request("GET", path`/coupons/${couponId}/issues`, pageSchema(couponIssueSchema), {
+          query: params as Query,
+        }),
+      redemptions: (
+        couponId: string,
+        params?: PageParams & { status?: "RESERVED" | "USED" | "RELEASED" | "RESTORED" },
+      ) =>
+        storeHttp.request(
+          "GET",
+          path`/coupons/${couponId}/redemptions`,
+          pageSchema(couponRedemptionSchema),
+          { query: params as Query },
+        ),
+      stats: (couponId: string) =>
+        storeHttp.request("GET", path`/coupons/${couponId}/stats`, couponStatsSchema),
+      /** 발급 쿠폰 회수 — 사용 가능한 발급 쿠폰만 */
+      revokeIssue: (issueId: string) =>
+        storeHttp.request("POST", path`/coupon-issues/${issueId}/revoke`, couponIssueSchema),
+    },
+
     customerInquiries: {
       list: (
         params?: PageParams & {

package/src/index.ts

@@ -25,12 +25,17 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/common";
+export * from "./schemas/coupon";
 export * from "./schemas/customer";
+export * from "./schemas/digital-asset";
+export * from "./schemas/fulfillment";
+export * from "./schemas/fulfillment-code";
 export * from "./schemas/login";
 export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";
 export * from "./schemas/product";
+export * from "./schemas/promotion";
 export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";

package/src/schemas/claim.ts

@@ -85,6 +85,14 @@ export const claimSchema = z.object({
       trackingNumber: z.string().nullable(),
     })
     .nullable(),
+  fulfillmentType: z
+    .string()
+    .optional()
+    .default("SHIPPING")
+    .describe(
+      "클레임 대상 주문상품의 상품 유형(이슈 #48). 수거가 없는 비실물(`DOWNLOAD`·`CODE`·`SERVICE`) 반품은 수거 등록 없이 " +
+        "접수·보류에서 바로 승인한다. 값이 추가될 수 있어 문자열로 받는다. 서버는 항상 싣는다",
+    ),
   requestedAt: z.string(),
   completedAt: z.string().nullable(),
   /** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
@@ -163,8 +171,8 @@ export const approveClaimResultSchema = z.object({
     .number()
     .int()
     .describe(
-      "실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − " +
-        "추가 차감(`deductAmount`)",
+      "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − " +
+        "쿠폰 조건 미달 차감(`couponChargeAmount`) + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)",
     ),
   deductAmount: z.number().int().describe("승인 때 셀러가 추가로 차감한 금액"),
   quantity: z.number().int().describe("환불한 수량"),
@@ -179,6 +187,20 @@ export const approveClaimResultSchema = z.object({
       "환불액에서 뺀 **배송비** — 반품·교환 배송비 + 조건부 무료배송 미달 차감. " +
         "추가 차감(`deductAmount`)은 포함하지 않는다",
     ),
+  couponChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 쿠폰 조건 미달 차감. 남은 주문상품이 쿠폰 조건을 잃었을 때만 0보다 크다. 서버는 항상 싣는다",
+    ),
+  couponChargeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
   refundedAt: z.string(),
 });
 

package/src/schemas/coupon.ts

@@ -0,0 +1,312 @@
+import { z } from "zod";
+import { pageQueryShape } from "./common";
+import {
+  COUPON_CONDITIONS_DEFAULTS,
+  COUPON_TARGET_LIST_MAX,
+  couponBenefitSchema,
+  couponConditionsSchema,
+  couponKindSchema,
+  couponTargetSchema,
+} from "./promotion";
+
+/**
+ * 쿠폰 관리 API 계약 (이슈 #47) — `/v1/coupons/**`, 스코프 `promotion:r|rw`.
+ *
+ * 금액 계산 규칙은 `promotion.ts`(`quotePricing`)가 원천이고, 여기에는 셀러가 쿠폰을 만들고 나눠 주는 표면만 있다.
+ * 발급·사용이 시작된 쿠폰은 혜택·조건·대상·사용 시작일을 바꿀 수 없다(409 `COUPON_LOCKED`). 이름·설명·종료일 연장·
+ * 한도 상향·중지·재개·종료만 된다. 규칙을 바꾸려면 새 쿠폰을 만든다.
+ */
+
+/** 쿠폰 상태 — `ACTIVE`(사용 중)·`PAUSED`(중지, 재개 가능)·`ENDED`(종료, 되돌릴 수 없음) */
+export const couponStatusSchema = z
+  .enum(["ACTIVE", "PAUSED", "ENDED"])
+  .describe("쿠폰 상태. `ACTIVE`=사용 중, `PAUSED`=중지(재개 가능), `ENDED`=종료(되돌릴 수 없음)");
+export type CouponStatus = z.infer<typeof couponStatusSchema>;
+
+/** 지금 만들 수 있는 발급 방식 — 다운로드·가입 자동 지급은 뒤 단계다 */
+export const couponIssueMethodSchema = z
+  .enum(["CODE", "MANUAL"])
+  .describe(
+    "발급 방식. `CODE`=구매자가 주문서에 코드를 입력한다, `MANUAL`=셀러가 회원을 골라 지급한다",
+  );
+export type CouponIssueMethod = z.infer<typeof couponIssueMethodSchema>;
+
+/** 코드 형식 — 영문·숫자·`-`·`_` 6~30자. 대소문자를 구분하지 않고 서버가 대문자로 저장한다 */
+export const COUPON_CODE_PATTERN = /^[A-Za-z0-9_-]{6,30}$/;
+
+/** 코드 정규화 — 대문자, 앞뒤 공백 제거. 입력·저장·조회가 같은 함수를 쓴다 */
+export function normalizeCouponCode(code: string): string {
+  return code.trim().toUpperCase();
+}
+
+const limitField = (description: string) =>
+  z.number().int().min(1).max(10_000_000).nullable().optional().describe(description);
+
+const descriptions = {
+  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인 사용 수 한도(코드 입력형). 생략하면 무제한. 비회원에게 여는 쿠폰은 둘 수 없다",
+} as const;
+
+/** 조건 입력 — 생략한 항목은 기본값(`COUPON_CONDITIONS_DEFAULTS`)이다 */
+export const couponConditionsInputSchema = z.strictObject({
+  minOrderAmount: z.number().int().min(0).optional(),
+  firstOrderOnly: z.boolean().optional(),
+  memberOnly: z.boolean().optional(),
+  stackWithInstantDiscount: z.boolean().optional(),
+});
+
+/** 대상 입력 — 생략한 목록은 빈 목록이다(포함 목록이 모두 비면 전 상품) */
+export const couponTargetInputSchema = z.strictObject({
+  includeProductIds: z.array(z.string().min(1)).max(COUPON_TARGET_LIST_MAX).optional(),
+  includeCategoryIds: z.array(z.string().min(1)).max(COUPON_TARGET_LIST_MAX).optional(),
+  excludeProductIds: z.array(z.string().min(1)).max(COUPON_TARGET_LIST_MAX).optional(),
+  excludeCategoryIds: z.array(z.string().min(1)).max(COUPON_TARGET_LIST_MAX).optional(),
+});
+
+const couponTimeField = (description: string) =>
+  z.iso.datetime({ offset: true }).nullable().optional().describe(description);
+
+/** `POST /v1/coupons` */
+export const createCouponRequestSchema = z
+  .strictObject({
+    name: z.string().trim().min(1).max(60).describe(descriptions.name),
+    description: z.string().max(300).nullable().optional().describe(descriptions.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.code),
+    startsAt: couponTimeField(descriptions.startsAt),
+    endsAt: couponTimeField(descriptions.endsAt),
+    validDaysAfterIssue: z
+      .number()
+      .int()
+      .min(1)
+      .max(3650)
+      .nullable()
+      .optional()
+      .describe(descriptions.validDaysAfterIssue),
+    totalIssueLimit: limitField(descriptions.totalIssueLimit),
+    totalUseLimit: limitField(descriptions.totalUseLimit),
+    perMemberIssueLimit: limitField(descriptions.perMemberIssueLimit),
+    perMemberUseLimit: limitField(descriptions.perMemberUseLimit),
+  })
+  .superRefine((body, ctx) => {
+    const issue = (path: string, message: string) =>
+      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인 발급 수 한도를 쓰십시오",
+      );
+    }
+    const memberOnly = body.conditions?.memberOnly ?? COUPON_CONDITIONS_DEFAULTS.memberOnly;
+    if (!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", "종료 시각은 시작 시각보다 뒤여야 합니다");
+    }
+  });
+export type CreateCouponRequest = z.infer<typeof createCouponRequestSchema>;
+
+/**
+ * `PATCH /v1/coupons/{couponId}` — 준 항목만 바뀐다. 발급·사용이 시작된 쿠폰(`locked`)은 이름·설명·종료일 연장·
+ * 한도 상향만 받고, 그 밖의 항목이 현재 값과 다르면 409 `COUPON_LOCKED`다. 종류·발급 방식은 바꿀 수 없다.
+ */
+export const updateCouponRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(60).optional().describe(descriptions.name),
+  description: z.string().max(300).nullable().optional().describe(descriptions.description),
+  benefit: couponBenefitSchema.optional(),
+  conditions: couponConditionsInputSchema.optional(),
+  target: couponTargetInputSchema.optional(),
+  code: z.string().regex(COUPON_CODE_PATTERN).optional().describe(descriptions.code),
+  startsAt: couponTimeField(descriptions.startsAt),
+  endsAt: couponTimeField(descriptions.endsAt),
+  validDaysAfterIssue: z.number().int().min(1).max(3650).nullable().optional(),
+  totalIssueLimit: limitField(descriptions.totalIssueLimit),
+  totalUseLimit: limitField(descriptions.totalUseLimit),
+  perMemberIssueLimit: limitField(descriptions.perMemberIssueLimit),
+  perMemberUseLimit: limitField(descriptions.perMemberUseLimit),
+});
+export type UpdateCouponRequest = z.infer<typeof updateCouponRequestSchema>;
+
+/** 쿠폰 응답 */
+export 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(),
+});
+export type Coupon = z.infer<typeof couponSchema>;
+
+/** `GET /v1/coupons` 쿼리 */
+export const couponListQuerySchema = z.object({
+  status: couponStatusSchema.optional(),
+  kind: couponKindSchema.optional(),
+  issueMethod: couponIssueMethodSchema.optional(),
+  q: z.string().optional().describe("이름·코드 검색(포함)"),
+  ...pageQueryShape(),
+});
+
+/** 발급 쿠폰 상태 — 만료는 저장 상태가 아니라 조회 시각으로 판정한 값이다 */
+export const couponIssueStatusSchema = z
+  .string()
+  .describe(
+    "발급 쿠폰 상태. 현재 값은 `AVAILABLE`(사용 가능)·`RESERVED`(결제 중)·`USED`(사용함)·`REVOKED`(회수)·" +
+      "`EXPIRED`(유효 기간 지남)이고 값이 추가될 수 있어 문자열로 받는다",
+  );
+
+export 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(),
+});
+export type CouponIssue = z.infer<typeof couponIssueSchema>;
+
+export const couponIssueListQuerySchema = z.object({
+  status: z.enum(["AVAILABLE", "RESERVED", "USED", "REVOKED"]).optional(),
+  ...pageQueryShape(),
+});
+
+/** `POST /v1/coupons/{couponId}/issues` — 셀러 지급. 한 번에 1,000명까지 */
+export const issueCouponRequestSchema = z.strictObject({
+  customerIds: z
+    .array(z.string().min(1))
+    .min(1)
+    .max(1000)
+    .refine((ids) => new Set(ids).size === ids.length, "같은 구매자를 두 번 넣었습니다")
+    .describe("지급할 구매자 id(1~1,000명, 중복 불가)"),
+});
+export type IssueCouponRequest = z.infer<typeof issueCouponRequestSchema>;
+
+export 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(),
+    }),
+  ),
+});
+export type IssueCouponResult = z.infer<typeof issueCouponResultSchema>;
+
+export 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`(종료된 쿠폰)"),
+});
+export type CouponRedemption = z.infer<typeof couponRedemptionSchema>;
+
+export const couponRedemptionListQuerySchema = z.object({
+  status: z.enum(["RESERVED", "USED", "RELEASED", "RESTORED"]).optional(),
+  ...pageQueryShape(),
+});
+
+export 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`) 주문의 결제 금액 합계 (원). 부분 취소·반품 환불은 빼지 않은 결제 시점 금액이다",
+    ),
+});
+export type CouponStats = z.infer<typeof couponStatsSchema>;
+
+/** `GET /v1/customers/{customerId}/coupons` 항목 — 발급 쿠폰 + 쿠폰 이름·혜택 */
+export const customerCouponSchema = couponIssueSchema.extend({
+  couponName: z.string(),
+  kind: couponKindSchema,
+  benefit: couponBenefitSchema,
+});
+export type CustomerCoupon = z.infer<typeof customerCouponSchema>;