@sayren/storefront-sdk 0.13.0 → 0.15.0

package/src/schemas/coupon.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+
+/**
+ * 스토어프론트 쿠폰 계약 (이슈 #47).
+ *
+ * 구매자는 주문서에서 쿠폰을 고르거나 코드를 입력한다. 금액 미리보기(`POST /checkout/{checkoutId}/pricing`)는
+ * 주문서를 바꾸지 않는 읽기 계산이고, **확정은 결제 시작(`coupons` 필드)만 한다** — 결제 시작이 쿠폰을 예약하고 그 금액으로
+ * 결제 금액을 정한다. 결제가 실패하거나 만료되면 예약이 풀려 같은 쿠폰을 다시 쓸 수 있다.
+ *
+ * 한 주문에 주문 쿠폰 1장, 주문상품 한 줄에 상품 쿠폰 1장까지다. 같은 쿠폰을 두 번 쓸 수 없다.
+ */
+
+/** 적용할 쿠폰 한 장 — 발급 쿠폰 id 또는 코드 중 하나 */
+export const couponApplicationSchema = z
+  .object({
+    issueId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe("내 쿠폰(발급 쿠폰) id — `GET /me/coupons`의 `issueId`"),
+    code: z
+      .string()
+      .trim()
+      .min(1)
+      .max(30)
+      .optional()
+      .describe("쿠폰 코드. 대소문자를 구분하지 않는다"),
+    optionId: z
+      .string()
+      .optional()
+      .describe(
+        "상품 쿠폰을 걸 주문서 항목의 `optionId`. 생략하면 할인이 가장 큰 항목에 건다. 주문 쿠폰에는 쓰지 않는다",
+      ),
+  })
+  .refine((value) => (value.issueId ? 1 : 0) + (value.code ? 1 : 0) === 1, {
+    message: "issueId와 code 중 하나만 보내 주십시오",
+  });
+export type CouponApplication = z.infer<typeof couponApplicationSchema>;
+
+/** 한 번에 적용할 수 있는 쿠폰 수 */
+export const MAX_COUPONS_PER_CHECKOUT = 5;
+
+export const couponApplicationListSchema = z
+  .array(couponApplicationSchema)
+  .max(MAX_COUPONS_PER_CHECKOUT)
+  .describe("적용할 쿠폰. 주문 쿠폰 1장, 주문상품 한 줄에 상품 쿠폰 1장까지 함께 쓴다");
+
+/** 쿠폰 혜택 — 응답 표시용. 값이 늘 수 있어 방식은 문자열이다 */
+export const couponBenefitViewSchema = z.object({
+  type: z.string().describe("할인 방식. 현재 값은 `RATE`(정률 %)·`AMOUNT`(정액 원)"),
+  value: z.number().int().describe("정률이면 %, 정액이면 원"),
+  maxDiscountAmount: z.number().int().nullable().describe("정률 할인의 최대 할인액. 없으면 null"),
+});
+
+/** 쿠폰 한 장의 적용 결과 */
+export const couponResultSchema = z.object({
+  couponId: z.string(),
+  issueId: z.string().nullable().describe("발급 쿠폰 id. 코드로 적용했으면 null"),
+  code: z.string().nullable().describe("코드로 적용했으면 그 코드(대문자). 그 밖은 null"),
+  name: z.string(),
+  kind: z.string().describe("쿠폰 종류. 현재 값은 `ORDER`(주문 쿠폰)·`PRODUCT`(상품 쿠폰)"),
+  benefit: couponBenefitViewSchema,
+  applied: z.boolean(),
+  discountAmount: z.number().int().describe("이 쿠폰의 할인액. 적용하지 못했으면 0"),
+  rejectReason: z
+    .string()
+    .nullable()
+    .describe(
+      "적용하지 못한 사유. `MIN_ORDER_AMOUNT`(최소 주문 금액 미달)·`NO_ELIGIBLE_ITEMS`(대상 상품 없음)·`NOT_STARTED`·`EXPIRED`·" +
+        "`MEMBER_ONLY`(회원 전용)·`STACK_LIMIT`(같은 종류 쿠폰이 이미 적용됨)·`DUPLICATE_COUPON`·`LINE_NOT_ELIGIBLE`·`NO_DISCOUNT`·" +
+        "`IN_USE`(다른 결제에서 쓰는 중)·`LIMIT_REACHED`(1인 사용 한도)·`EXHAUSTED`(총 사용 한도)·`INACTIVE`(중지된 쿠폰). 값이 늘 수 있다",
+    ),
+  optionId: z
+    .string()
+    .nullable()
+    .describe("상품 쿠폰이 걸린 주문서 항목의 `optionId`. 그 밖은 null"),
+});
+export type CouponResult = z.infer<typeof couponResultSchema>;
+
+/** 쿠폰을 반영한 금액 — 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount */
+export const pricingAmountsSchema = z.object({
+  productAmount: z.number().int(),
+  deliveryFee: z.number().int(),
+  couponDiscountAmount: z.number().int(),
+  deliveryDiscountAmount: z.number().int(),
+  totalAmount: z.number().int().describe("결제 금액"),
+});
+
+/** `POST /checkout/{checkoutId}/pricing` 요청 */
+export const checkoutPricingRequestSchema = z.object({
+  zipCode: z
+    .string()
+    .regex(/^[0-9]{5}$/, "우편번호 5자리를 입력해 주십시오")
+    .optional()
+    .describe("배송지 우편번호. 주면 제주·도서산간 추가 배송비까지 반영한다"),
+  coupons: couponApplicationListSchema,
+});
+export type CheckoutPricingRequest = z.infer<typeof checkoutPricingRequestSchema>;
+
+/** 결제 금액의 하한 — 쿠폰 적용 뒤 결제 금액이 이보다 작으면 결제를 시작할 수 없다 */
+export const MIN_PAYMENT_AMOUNT = 100;
+
+export const checkoutPricingSchema = z.object({
+  amounts: pricingAmountsSchema,
+  coupons: z.array(couponResultSchema).describe("요청한 쿠폰마다 한 줄, 요청 순서대로"),
+  items: z
+    .array(
+      z.object({
+        optionId: z.string().nullable(),
+        couponDiscountAmount: z.number().int().describe("이 항목에 들어간 쿠폰 할인"),
+      }),
+    )
+    .describe("주문서 항목별 쿠폰 할인 — 주문서 `items`와 같은 순서"),
+  payable: z
+    .boolean()
+    .describe(
+      "이 금액으로 결제를 시작할 수 있는가 — 적용하지 못한 쿠폰이 있거나 결제 금액이 100원 미만이면 false",
+    ),
+});
+export type CheckoutPricing = z.infer<typeof checkoutPricingSchema>;
+
+/** `GET /checkout/{checkoutId}/coupons` 항목 — 이 주문서에 쓸 수 있는 내 쿠폰 */
+export const applicableCouponSchema = z.object({
+  issueId: z.string(),
+  couponId: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  kind: z.string(),
+  benefit: couponBenefitViewSchema,
+  minOrderAmount: z.number().int(),
+  validUntil: z.string().nullable().describe("유효 기간 끝(이 시각부터 못 쓴다). 없으면 null"),
+  applicable: z.boolean().describe("이 주문서에 혼자 적용하면 할인이 되는가"),
+  expectedDiscountAmount: z.number().int().describe("혼자 적용했을 때의 예상 할인액"),
+  rejectReason: z
+    .string()
+    .nullable()
+    .describe("적용할 수 없는 사유(`couponResultSchema.rejectReason`과 같은 값)"),
+});
+export type ApplicableCoupon = z.infer<typeof applicableCouponSchema>;
+
+/** `GET /me/coupons` 항목 */
+export const myCouponSchema = z.object({
+  issueId: z.string(),
+  couponId: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  kind: z.string(),
+  benefit: couponBenefitViewSchema,
+  minOrderAmount: z.number().int(),
+  status: z
+    .string()
+    .describe(
+      "상태. 현재 값은 `AVAILABLE`(사용 가능)·`RESERVED`(결제 중)·`USED`(사용함)·`EXPIRED`(기간 지남)이고 값이 늘 수 있다",
+    ),
+  validFrom: z.string(),
+  validUntil: z.string().nullable(),
+  usedOrderId: z.string().nullable(),
+  issuedAt: z.string(),
+});
+export type MyCoupon = z.infer<typeof myCouponSchema>;
+
+export const myCouponListQuerySchema = z.object({
+  status: z
+    .enum(["available", "used", "expired"])
+    .optional()
+    .describe(
+      "`available`=사용 가능(결제 중 포함), `used`=사용함, `expired`=기간 지남. 생략하면 전부",
+    ),
+});

package/src/schemas/fulfillment.ts

@@ -0,0 +1,181 @@
+import { z } from "zod";
+
+/**
+ * 구매자용 상품 이행 (이슈 #57) — 관리 API의 상품 이행에서 구매자에게 필요한 것만 싣는다. 유형, 배송 필요 여부, 배송 안내(배송비·
+ * 무료 기준·반품·교환 배송비), 청약철회 제한 여부, 방문 수령지 표시값이다. 셀러 내부 값(출고지·반품지 id, 코드 풀 여부, 재고 추적 여부)은
+ * 싣지 않는다.
+ *
+ * 유형 이름은 응답에서 문자열이고, 모르는 유형(서버가 나중에 더한 유형, 예: #56 `RESERVATION`)은 `{ type: "OTHER", rawType,
+ * requiresShipping }`로 읽는다. `requiresShipping`은 판별 값에서 파생되지만 **모든 가지에 싣는다** — 모르는 유형에서도 주문서가
+ * 배송지를 받을지 정할 수 있어야 한다.
+ */
+
+const KNOWN_TYPES: readonly string[] = ["SHIPPING", "DOWNLOAD", "CODE", "SERVICE", "PICKUP"];
+
+/** 모르는 유형 — SDK가 아직 모르는 유형이다 */
+export interface UnknownFulfillmentView {
+  type: "OTHER";
+  /** 서버가 보낸 유형 이름 */
+  rawType: string;
+  requiresShipping: boolean;
+}
+
+/** 알려진 유형만 판별 유니온으로 검사하고 모르는 유형은 `OTHER`로 읽는다. 알려진 유형의 모양이 틀리면 파싱 오류다 */
+function openUnion<T extends z.ZodType>(known: T) {
+  return z.union([
+    known,
+    z
+      .looseObject({
+        type: z.string().refine((type) => !KNOWN_TYPES.includes(type), {
+          message: "알려진 유형은 해당 유형의 모양이어야 합니다",
+        }),
+        requiresShipping: z.boolean(),
+      })
+      .transform(
+        (value): UnknownFulfillmentView => ({
+          type: "OTHER",
+          rawType: value.type,
+          requiresShipping: value.requiresShipping,
+        }),
+      ),
+  ]);
+}
+
+const requiresShippingDescription =
+  "택배 배송이 필요한가. false면 배송비가 없고 주문서가 배송지를 받지 않는다";
+
+const withdrawalRestrictedField = z
+  .boolean()
+  .describe(
+    "청약철회 제한 대상인가. true면 주문서가 제한 고지 동의를 받고, 첫 다운로드·열람 뒤 단순 변심 취소·반품을 받지 않는다",
+  );
+
+/** 방문 수령 장소 표시값 — 주소 id는 싣지 않는다 */
+export const pickupLocationSchema = z.object({
+  name: z.string().describe("수령 장소 이름"),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+  phone: z.string().describe("수령 장소 연락처"),
+});
+
+export type PickupLocation = z.infer<typeof pickupLocationSchema>;
+
+/** 상품 카드(목록·찜)의 이행 — 유형과 배송 필요 여부만. 배송비·환불 정책은 상세에서 본다 */
+export const productCardFulfillmentSchema = z.object({
+  type: z.string().describe("상품 유형. 값이 추가될 수 있어 문자열로 받는다"),
+  requiresShipping: z.boolean().describe(requiresShippingDescription),
+});
+
+export type ProductCardFulfillment = z.infer<typeof productCardFulfillmentSchema>;
+
+/** 상품 상세의 이행 */
+export const productFulfillmentViewSchema = openUnion(
+  z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("SHIPPING"),
+      requiresShipping: z.literal(true),
+      shipping: z.object({
+        deliveryType: z
+          .string()
+          .describe("배송비 유형. 현재 값은 `FREE`·`PAID`·`CONDITIONAL_FREE`"),
+        deliveryFee: z
+          .number()
+          .int()
+          .describe("기본 배송비. 원 단위. 묶음·지역 추가 배송비는 장바구니·주문서 견적이 정한다"),
+        conditionalFreeAmount: z
+          .number()
+          .int()
+          .nullable()
+          .describe("조건부 무료 기준 금액. 조건부 무료가 아니면 null"),
+        estimatedDays: z.string().describe("예상 배송 기간 안내 문구"),
+        returnDeliveryFee: z
+          .number()
+          .int()
+          .describe("단순 변심 반품 배송비(유효 환불 정책). 원 단위"),
+        exchangeDeliveryFee: z
+          .number()
+          .int()
+          .describe("단순 변심 교환 배송비(유효 환불 정책). 원 단위"),
+      }),
+    }),
+    z.object({
+      type: z.literal("DOWNLOAD"),
+      requiresShipping: z.literal(false),
+      download: z.object({
+        limit: z.number().int().describe("다운로드 횟수 한도(수량 1개당)"),
+        days: z.number().int().describe("다운로드 기간(제공일부터 일수)"),
+        withdrawalRestricted: withdrawalRestrictedField,
+      }),
+    }),
+    z.object({
+      type: z.literal("CODE"),
+      requiresShipping: z.literal(false),
+      code: z.object({ withdrawalRestricted: withdrawalRestrictedField }),
+    }),
+    z.object({ type: z.literal("SERVICE"), requiresShipping: z.literal(false) }),
+    z.object({
+      type: z.literal("PICKUP"),
+      requiresShipping: z.literal(false),
+      pickup: z.object({
+        location: pickupLocationSchema
+          .nullable()
+          .describe("방문 수령 장소. 수령지가 지워졌으면 null이다(판매자에게 문의)"),
+      }),
+    }),
+  ]),
+).describe(
+  "상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 안내다. 값이 추가될 수 있어 SDK는 모르는 유형을 `OTHER`로 읽는다",
+);
+
+export type ProductFulfillmentView = z.infer<typeof productFulfillmentViewSchema>;
+
+/** 장바구니 줄·주문서 줄의 이행 — 주문서 줄은 주문서 시점 스냅샷이다 */
+export const lineFulfillmentSchema = z.object({
+  type: z.string().describe("상품 유형. 값이 추가될 수 있어 문자열로 받는다"),
+  requiresShipping: z.boolean().describe(requiresShippingDescription),
+  withdrawalRestricted: withdrawalRestrictedField,
+});
+
+export type LineFulfillment = z.infer<typeof lineFulfillmentSchema>;
+
+/**
+ * 내 주문 주문상품의 주문 시점 이행 스냅샷. 상품을 나중에 고쳐도 바뀌지 않는다. 실제 제공 기록(코드 가린 값·다운로드 남은 횟수)은
+ * 주문상품의 `fulfillment`다.
+ */
+export const myOrderItemFulfillmentSnapshotSchema = openUnion(
+  z.discriminatedUnion("type", [
+    z.object({ type: z.literal("SHIPPING"), requiresShipping: z.literal(true) }),
+    z.object({
+      type: z.literal("DOWNLOAD"),
+      requiresShipping: z.literal(false),
+      download: z.object({ withdrawalRestricted: withdrawalRestrictedField }),
+    }),
+    z.object({
+      type: z.literal("CODE"),
+      requiresShipping: z.literal(false),
+      code: z.object({ withdrawalRestricted: withdrawalRestrictedField }),
+    }),
+    z.object({ type: z.literal("SERVICE"), requiresShipping: z.literal(false) }),
+    z.object({
+      type: z.literal("PICKUP"),
+      requiresShipping: z.literal(false),
+      pickup: z.object({
+        location: pickupLocationSchema
+          .nullable()
+          .describe("주문 시점 방문 수령 장소. 수령지가 지워졌으면 null이다(판매자에게 문의)"),
+      }),
+    }),
+  ]),
+).describe("주문 시점 이행 스냅샷. 값이 추가될 수 있어 SDK는 모르는 유형을 `OTHER`로 읽는다");
+
+export type MyOrderItemFulfillmentSnapshot = z.infer<typeof myOrderItemFulfillmentSnapshotSchema>;
+
+/** 청약철회 제한 대상인가 — 파일 다운로드·코드 발급만 켤 수 있다 */
+export function withdrawalRestrictedOfView(
+  fulfillment: ProductFulfillmentView | MyOrderItemFulfillmentSnapshot,
+): boolean {
+  if (fulfillment.type === "DOWNLOAD") return fulfillment.download.withdrawalRestricted;
+  if (fulfillment.type === "CODE") return fulfillment.code.withdrawalRestricted;
+  return false;
+}

package/src/schemas/order.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { easyPayProviderResponseSchema, paymentMethodSchema } from "./checkout";
 import { orderItemStatusSchema } from "./common";
+import { myOrderItemFulfillmentSnapshotSchema } from "./fulfillment";
 
 export const myOrderItemSchema = z.object({
   orderItemId: z.string(),
@@ -20,8 +21,69 @@ export const myOrderItemSchema = z.object({
     .number()
     .int()
     .describe("남은 수량 (`quantity` − `canceledQuantity`). 취소·반품·교환 요청 수량의 상한이다"),
-  totalPrice: z.number().int(),
+  totalPrice: z.number().int().describe("주문상품 금액 (즉시할인 반영, 쿠폰 전)"),
+  couponDiscountAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이 주문상품에 배분된 쿠폰 할인. 실결제 금액은 `totalPrice − couponDiscountAmount`다. 쿠폰이 없으면 0. 서버는 항상 싣는다",
+    ),
   status: orderItemStatusSchema,
+  fulfillmentSnapshot: myOrderItemFulfillmentSnapshotSchema.describe(
+    "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 `DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. " +
+      "청약철회 제한 주문상품(`download`·`code`의 `withdrawalRestricted`)은 제공이 시작되면(다운로드·열람) 구매자 취소·반품을 받지 않는다",
+  ),
+  fulfillment: z
+    .object({
+      status: z
+        .string()
+        .describe(
+          "제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다",
+        ),
+      fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
+      note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
+      codes: z
+        .array(
+          z.object({
+            codeId: z.string(),
+            hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
+            revealedAt: z.string().nullable().describe("처음 열람한 시각. 열람 전이면 null"),
+          }),
+        )
+        .optional()
+        .default([])
+        .describe(
+          "코드 발급 상품의 코드(가린 값). 평문은 `fulfillment/reveal`로 연다. 환불로 회수된 코드는 싣지 않는다. 서버는 항상 싣는다",
+        ),
+      download: z
+        .object({
+          count: z.number().int().describe("지금까지 받은 횟수"),
+          limit: z.number().int().describe("받을 수 있는 횟수"),
+          expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
+          files: z.array(
+            z.object({
+              assetId: z.string(),
+              fileName: z.string(),
+              sizeBytes: z.number().int().nullable(),
+            }),
+          ),
+        })
+        .nullable()
+        .optional()
+        .default(null)
+        .describe(
+          "파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 `downloads`로 받는다. 다른 유형은 null. 서버는 항상 싣는다",
+        ),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "비실물 상품(이용권·방문 수령 등)의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. " +
+        "비실물의 `DELIVERED`는 제공 완료(방문 수령은 수령 완료)로 표시한다. 서버는 항상 싣는다",
+    ),
   claimStatus: z.string().nullable(),
   reviewWritten: z.boolean(),
   autoDecisionDate: z.string().nullable(),
@@ -52,6 +114,11 @@ export const myOrderSchema = z.object({
   orderId: z.string(),
   orderedAt: z.string(),
   items: z.array(myOrderItemSchema),
+  requiresShipping: z
+    .boolean()
+    .describe(
+      "택배 배송이 필요한 주문상품이 있는가. false면 `shippingAddress`는 주문자 이름·연락처만 있고 주소는 빈 문자열이다",
+    ),
   shippingAddress: orderShippingAddressSchema,
   payment: z.object({
     method: paymentMethodSchema.describe(
@@ -66,10 +133,46 @@ export const myOrderSchema = z.object({
           "그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. " +
           "현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다",
       ),
-    totalAmount: z.number().int(),
+    couponDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("상품·주문 쿠폰 할인 합계. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    deliveryDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    discounts: z
+      .array(
+        z.object({
+          couponId: z.string(),
+          name: z.string().describe("주문 시점 쿠폰 이름"),
+          kind: z
+            .string()
+            .describe(
+              "쿠폰 종류. 현재 값은 `ORDER`·`PRODUCT`·`DELIVERY`이고 값이 추가될 수 있어 문자열로 받는다",
+            ),
+          discountAmount: z.number().int(),
+        }),
+      )
+      .optional()
+      .default([])
+      .describe("주문이 받은 쿠폰. 쿠폰이 없으면 빈 배열. 서버는 항상 싣는다"),
+    totalAmount: z.number().int().describe("결제 금액 (쿠폰 할인 반영)"),
     paidAt: z.string().nullable(),
     receiptUrl: z.url().nullable(),
   }),
+  withdrawalAgreedAt: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -136,3 +239,43 @@ export const purchaseDecisionResultSchema = z.object({
 });
 
 export type PurchaseDecisionResult = z.infer<typeof purchaseDecisionResultSchema>;
+
+/**
+ * 코드 열람 응답 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/fulfillment/reveal`(회원)·
+ * `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/fulfillment/reveal`(비회원).
+ * 평문 코드는 이 응답에만 있다. 화면에 보인 뒤 저장하지 않는다(응답은 `Cache-Control: no-store`).
+ * 첫 열람 시각은 청약철회 판단의 근거(제공 개시)로 남는다.
+ */
+export const fulfillmentRevealSchema = z.object({
+  orderItemId: z.string(),
+  codes: z.array(
+    z.object({
+      codeId: z.string(),
+      code: z.string().describe("코드 평문"),
+      revealedAt: z.string().describe("처음 열람한 시각"),
+    }),
+  ),
+});
+
+export type FulfillmentReveal = z.infer<typeof fulfillmentRevealSchema>;
+
+/**
+ * 다운로드 요청 (이슈 #48) — `POST /storefront/v1/me/order-items/{orderItemId}/downloads`(회원)·
+ * `POST /storefront/v1/guest/orders/{orderId}/order-items/{orderItemId}/downloads`(비회원, 연락처·비밀번호를 함께 보낸다).
+ * 파일이 하나면 `assetId`를 생략할 수 있다.
+ */
+export const downloadRequestSchema = z.object({
+  assetId: z.string().min(1).max(64).optional().describe("받을 파일. 파일이 여러 개면 필수다"),
+});
+
+export type DownloadRequest = z.infer<typeof downloadRequestSchema>;
+
+/** 다운로드 응답 — 수명 300초의 서명 주소. 받을 때마다 횟수가 하나 준다 */
+export const downloadLinkSchema = z.object({
+  url: z.url().describe("서명 주소. 300초 뒤 만료된다 — 받아서 바로 쓰고 저장하지 않는다"),
+  expiresAt: z.string().describe("서명 주소 만료 시각"),
+  fileName: z.string(),
+  remaining: z.number().int().describe("남은 다운로드 횟수"),
+});
+
+export type DownloadLink = z.infer<typeof downloadLinkSchema>;