@sayren/store-sdk 0.15.1 → 0.17.0

package/src/schemas/digital-asset.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+/**
+ * 파일 다운로드 상품의 판매 파일 (이슈 #48 단계 3).
+ *
+ * 파일은 CDN **비공개 객체**다. `POST /v1/uploads`(`purpose: "digital-asset"`)로 자리를 받아 응답의 `headers`와 함께 PUT하고,
+ * 응답의 `key`로 상품에 연결한다. 객체 키와 파일 주소는 어떤 응답에도 싣지 않는다 — 구매자는 제공된 주문상품에서
+ * 수명 300초의 서명 주소로만 받는다. 주문은 주문 시점 파일을 스냅샷하므로 파일을 바꿔도 이미 산 구매자는 옛 파일을 받는다.
+ */
+
+export const digitalAssetAttachRequestSchema = z.object({
+  key: z
+    .string()
+    .min(1)
+    .max(512)
+    .describe("업로드 자리 발급 응답의 `key`. 이 스토어의 비공개 업로드 키여야 한다"),
+  fileName: z.string().trim().min(1).max(200).describe("구매자에게 보일 파일 이름(확장자 포함)"),
+  sizeBytes: z.number().int().positive().optional().describe("파일 크기(바이트). 안내용이다"),
+  contentType: z.string().max(200).optional().describe("파일 형식(MIME). 안내용이다"),
+  variantId: z
+    .string()
+    .optional()
+    .describe("이 파일을 줄 옵션(variant). 생략하면 모든 옵션의 구매자가 받는다"),
+});
+export type DigitalAssetAttachRequest = z.infer<typeof digitalAssetAttachRequestSchema>;
+
+/** 판매 파일 — 객체 키·주소는 싣지 않는다 */
+export const digitalAssetSchema = z.object({
+  assetId: z.string(),
+  productId: z.string(),
+  variantId: z.string().nullable().describe("옵션 전용 파일이면 그 옵션, 모든 옵션 공통이면 null"),
+  fileName: z.string(),
+  contentType: z.string().nullable(),
+  sizeBytes: z.number().int().nullable(),
+  status: z
+    .string()
+    .describe(
+      "`ACTIVE`(새 주문에 제공)·`REMOVED`(해제 — 이미 산 구매자는 계속 받는다). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  createdAt: z.string(),
+});
+export type DigitalAsset = z.infer<typeof digitalAssetSchema>;
+
+/** 셀러 확인용 서명 주소 — `POST /v1/products/{productId}/digital-assets/{assetId}/preview-url` */
+export const digitalAssetPreviewSchema = z.object({
+  url: z.url().describe("수명 300초의 서명 주소"),
+  expiresAt: z.string(),
+});
+export type DigitalAssetPreview = z.infer<typeof digitalAssetPreviewSchema>;
+
+/** 주문상품의 다운로드 제공 정보 — 주문 응답의 `fulfillment.download` */
+export const orderItemDownloadSchema = z.object({
+  count: z.number().int().describe("지금까지 받은 횟수"),
+  limit: z.number().int().describe("받을 수 있는 횟수"),
+  expiresAt: z.string().nullable().describe("받을 수 있는 기한 (ISO 8601)"),
+  firstDownloadedAt: z.string().nullable().describe("처음 받은 시각 — 제공 개시 증거다"),
+  files: z.array(
+    z.object({
+      assetId: z.string(),
+      fileName: z.string(),
+      sizeBytes: z.number().int().nullable(),
+    }),
+  ),
+});
+export type OrderItemDownload = z.infer<typeof orderItemDownloadSchema>;

package/src/schemas/fulfillment-code.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { pageQueryShape, pageSchema } from "./common";
+
+/**
+ * 코드 발급 상품의 코드 풀 (이슈 #48 단계 2) — 라이선스 키·기프트 코드처럼 결제 확정과 함께 한 개씩 배정하는 코드다.
+ *
+ * **평문 코드는 두 경로로만 나간다** — 구매자 열람(`POST /storefront/v1/me/order-items/{id}/fulfillment/reveal`)과 셀러 콘솔
+ * 열람(`POST /v1/fulfillment-codes/{codeId}/reveal`, 콘솔 전용). 목록·주문·웹훅·API 로그에는 가린 값(`hint`)만 싣는다.
+ * 코드는 결제 자격 증명과 같은 키링·AES-256-GCM으로 암호화해 저장한다.
+ */
+
+/**
+ * 코드 상태.
+ * - `AVAILABLE` 판매 가능 — 재고로 센다
+ * - `ASSIGNED` 주문상품에 배정됨
+ * - `REVOKED` 환불로 회수됨(구매자 화면에서 숨긴다. 코드 자체의 무효화는 셀러 시스템 몫이다)
+ * - `EXPIRED` 유효기간이 지나 배정하지 않음
+ * - `VOID` 셀러가 폐기함
+ */
+export const fulfillmentCodeStatusSchema = z.enum([
+  "AVAILABLE",
+  "ASSIGNED",
+  "REVOKED",
+  "EXPIRED",
+  "VOID",
+]);
+export type FulfillmentCodeStatus = z.infer<typeof fulfillmentCodeStatusSchema>;
+
+/** 한 번에 올릴 수 있는 코드 수 */
+export const MAX_CODES_PER_UPLOAD = 10_000;
+/** 코드 한 개의 최대 길이 */
+export const MAX_CODE_LENGTH = 200;
+
+/**
+ * 코드 일괄 업로드 요청 — `POST /v1/products/{productId}/codes`. `codes`(배열)와 `csv`(본문) 중 하나를 보낸다.
+ * 앞뒤 공백은 지우고 빈 줄은 건너뛴다. 같은 상품에 이미 있는 코드와 요청 안의 중복은 받지 않는다(`duplicates`).
+ */
+export const fulfillmentCodeUploadRequestSchema = z
+  .object({
+    variantId: z
+      .string()
+      .optional()
+      .describe("코드를 채울 옵션(variant) ID. 옵션 없는 상품은 생략한다(기본 옵션)"),
+    codes: z
+      .array(z.string())
+      .max(MAX_CODES_PER_UPLOAD)
+      .optional()
+      .describe(`코드 목록. 한 번에 ${MAX_CODES_PER_UPLOAD}개까지. \`csv\`와 둘 중 하나만 보낸다`),
+    csv: z
+      .string()
+      .max(4_000_000)
+      .optional()
+      .describe(
+        "CSV 본문 — 줄마다 첫 칸이 코드다. 첫 줄의 첫 칸이 `code`면 머리글로 보고 건너뛴다. " +
+          `한 번에 ${MAX_CODES_PER_UPLOAD}줄까지`,
+      ),
+    expiresAt: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe("이 업로드 코드의 유효기간 (ISO 8601). 지나면 배정하지 않고 만료로 바꾼다"),
+  })
+  .refine((value) => (value.codes === undefined) !== (value.csv === undefined), {
+    message: "codes와 csv 중 하나만 보내야 합니다",
+  });
+export type FulfillmentCodeUploadRequest = z.infer<typeof fulfillmentCodeUploadRequestSchema>;
+
+/** 받지 않은 줄 */
+export const fulfillmentCodeRejectionSchema = z.object({
+  line: z.number().int().describe("요청 안의 위치 (1부터). CSV는 머리글을 포함한 줄 번호다"),
+  reason: z
+    .string()
+    .describe(
+      "사유. `DUPLICATE`(이미 있는 코드이거나 요청 안에서 겹침)·`TOO_LONG`(200자 초과)·`INVALID_CHARACTER`(제어 문자). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+});
+
+/** 업로드 결과 — 배치 요약 */
+export const fulfillmentCodeBatchSchema = z.object({
+  batchId: z.string(),
+  productId: z.string(),
+  variantId: z.string(),
+  total: z.number().int().describe("요청에서 읽은 코드 수(빈 줄·머리글 제외)"),
+  accepted: z.number().int().describe("받은 코드 수 — 재고가 이만큼 는다"),
+  duplicates: z.number().int().describe("중복이라 받지 않은 코드 수"),
+  rejected: z
+    .array(fulfillmentCodeRejectionSchema)
+    .describe("받지 않은 줄(중복 포함). 최대 1,000개까지 싣는다"),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type FulfillmentCodeBatch = z.infer<typeof fulfillmentCodeBatchSchema>;
+
+/** 코드 목록의 한 줄 — **가린 값만** 싣는다 */
+export const fulfillmentCodeSchema = z.object({
+  codeId: z.string(),
+  productId: z.string(),
+  variantId: z.string(),
+  batchId: z.string().nullable().describe("업로드 배치. 수동 제공으로 셀러가 넘긴 코드는 null"),
+  hint: z.string().describe("가린 코드 — 끝 4자만 보인다(예: `****AB12`)"),
+  status: z
+    .string()
+    .describe(
+      "코드 상태. `AVAILABLE`·`ASSIGNED`·`REVOKED`·`EXPIRED`·`VOID`. 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  orderItemId: z.string().nullable().describe("배정된 주문상품. 배정 전이면 null"),
+  assignedAt: z.string().nullable(),
+  revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각 — 제공 개시 증거다"),
+  expiresAt: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type FulfillmentCode = z.infer<typeof fulfillmentCodeSchema>;
+
+export const fulfillmentCodePageSchema = pageSchema(fulfillmentCodeSchema).extend({
+  available: z.number().int().describe("판매 가능한 코드 수(필터와 무관한 상품 전체)"),
+});
+export type FulfillmentCodePage = z.infer<typeof fulfillmentCodePageSchema>;
+
+/** `GET /v1/products/{productId}/codes` 쿼리 */
+export const fulfillmentCodeListQuerySchema = z.object({
+  status: fulfillmentCodeStatusSchema.optional().describe("상태 필터"),
+  variantId: z.string().optional().describe("옵션 필터"),
+  batchId: z.string().optional().describe("업로드 배치 필터"),
+  orderItemId: z.string().optional().describe("주문상품 필터"),
+  ...pageQueryShape(),
+});
+
+/** 셀러 콘솔 코드 열람 응답 — `POST /v1/fulfillment-codes/{codeId}/reveal` */
+export const fulfillmentCodeRevealSchema = z.object({
+  codeId: z.string(),
+  code: z.string().describe("코드 평문. 응답은 캐시하지 않는다(`Cache-Control: no-store`)"),
+});
+export type FulfillmentCodeReveal = z.infer<typeof fulfillmentCodeRevealSchema>;
+
+/** 주문상품에 배정된 코드의 가린 값 — 주문 응답의 `fulfillment.codes` */
+export const orderItemCodeSchema = z.object({
+  codeId: z.string(),
+  hint: z.string().describe("가린 코드 — 끝 4자만 보인다"),
+  status: z
+    .string()
+    .describe("`ASSIGNED`(유효)·`REVOKED`(환불로 회수). 값이 추가될 수 있어 문자열로 받는다"),
+  revealedAt: z.string().nullable().describe("구매자가 처음 열람한 시각. 열람 전이면 null"),
+});
+export type OrderItemCode = z.infer<typeof orderItemCodeSchema>;

package/src/schemas/fulfillment.ts

@@ -0,0 +1,145 @@
+import { z } from "zod";
+
+/**
+ * 상품 유형과 제공 방식 (이슈 #48) — 배송이 필요 없는 상품을 팔기 위한 축이다.
+ *
+ * **상품 유형은 제공 방식 하나로 표현한다.** `fulfillmentType` 한 필드가 배송 필요 여부, 이행 흐름, 재고 의미를 정한다.
+ * 코드 곳곳에서 유형 이름으로 분기하지 않고 이 파일의 판정 함수(`requiresShipping`·`fulfillmentRuleOf`)를 지난다.
+ * 유형이 늘어나도 판정표 한 곳만 고치면 배송비 계산·결제 시작·클레임·콘솔 버튼이 같이 따라온다.
+ *
+ * 주문상품 상태 enum은 바꾸지 않는다. 비실물의 **제공 완료는 `DELIVERED`를 재사용한다** — 새 상태를 더하면 기존 소비자의
+ * 상태 분기(배송완료 뒤 구매확정 대기, 반품 가능 판정)가 새 값을 모른다. 표시는 `fulfillmentType`으로 가른다.
+ */
+
+/**
+ * 상품 유형.
+ * - `SHIPPING` 배송 상품(기본, 이 필드 이전의 상품 전부)
+ * - `DOWNLOAD` 파일 다운로드
+ * - `CODE` 코드 발급(라이선스 키·기프트 코드)
+ * - `SERVICE` 이용권·상품권·서비스(예약 없음)
+ * - `PICKUP` 방문 수령 실물
+ */
+export const fulfillmentTypeSchema = z.enum(["SHIPPING", "DOWNLOAD", "CODE", "SERVICE", "PICKUP"]);
+
+export type FulfillmentType = z.infer<typeof fulfillmentTypeSchema>;
+
+/** 제공 방식 — `AUTO`는 결제 확정과 함께 제공하고, `MANUAL`은 셀러가 제공 처리한다 */
+export const fulfillmentModeSchema = z.enum(["AUTO", "MANUAL"]);
+
+export type FulfillmentMode = z.infer<typeof fulfillmentModeSchema>;
+
+/**
+ * 응답 스키마용 유형 — 서버가 나중에 유형을 더해도 옛 SDK가 응답 파싱에서 깨지지 않게 문자열로 받는다.
+ * 요청은 `fulfillmentTypeSchema`(닫힌 enum)로 검증한다.
+ */
+export const fulfillmentTypeResponseSchema = z
+  .string()
+  .describe(
+    "상품 유형. 현재 값은 `SHIPPING`(배송 상품)·`DOWNLOAD`(파일 다운로드)·`CODE`(코드 발급)·`SERVICE`(이용권·서비스)·" +
+      "`PICKUP`(방문 수령)이고 값이 추가될 수 있어 문자열로 받는다",
+  );
+
+/** 유형 하나의 규칙 — 배송·제공·재고·클레임이 이 표를 읽는다 */
+export interface FulfillmentRule {
+  /** 택배 배송이 필요한가 — 배송비·배송지·발송 흐름의 대상인가 */
+  requiresShipping: boolean;
+  /** 허용하는 제공 방식. 배송 상품은 제공 방식이 없다(빈 배열) */
+  modes: readonly FulfillmentMode[];
+  /** 제공 방식을 정하지 않았을 때의 기본값. 배송 상품은 null */
+  defaultMode: FulfillmentMode | null;
+  /** 반품에 수거가 필요한가 — 실물만 수거한다(방문 수령 포함) */
+  requiresCollection: boolean;
+  /** 교환을 받는가 — 실물만 받는다 */
+  exchangeSupported: boolean;
+}
+
+/**
+ * 유형별 규칙표 — **유일한 원천이다.**
+ *
+ * `PICKUP`은 실물이라 반품 수거와 교환을 받지만 택배 배송은 없다. `DOWNLOAD`는 결제 즉시 권한을 발급하므로 `AUTO`만,
+ * `PICKUP`은 셀러가 수령 완료를 누르므로 `MANUAL`만 둔다.
+ */
+export const FULFILLMENT_RULES: Readonly<Record<FulfillmentType, FulfillmentRule>> = {
+  SHIPPING: {
+    requiresShipping: true,
+    modes: [],
+    defaultMode: null,
+    requiresCollection: true,
+    exchangeSupported: true,
+  },
+  DOWNLOAD: {
+    requiresShipping: false,
+    modes: ["AUTO"],
+    defaultMode: "AUTO",
+    requiresCollection: false,
+    exchangeSupported: false,
+  },
+  CODE: {
+    requiresShipping: false,
+    modes: ["AUTO", "MANUAL"],
+    defaultMode: "AUTO",
+    requiresCollection: false,
+    exchangeSupported: false,
+  },
+  SERVICE: {
+    requiresShipping: false,
+    modes: ["MANUAL", "AUTO"],
+    defaultMode: "MANUAL",
+    requiresCollection: false,
+    exchangeSupported: false,
+  },
+  PICKUP: {
+    requiresShipping: false,
+    modes: ["MANUAL"],
+    defaultMode: "MANUAL",
+    requiresCollection: true,
+    exchangeSupported: true,
+  },
+};
+
+/**
+ * 저장된 값 → 유형. null·모르는 값은 `SHIPPING`이다 — 이 필드 이전의 주문상품(`order_items.fulfillment_type` null)과
+ * 상품은 모두 배송 상품이었다.
+ */
+export function fulfillmentTypeOf(value: string | null | undefined): FulfillmentType {
+  const parsed = fulfillmentTypeSchema.safeParse(value);
+  return parsed.success ? parsed.data : "SHIPPING";
+}
+
+/** 유형의 규칙 — 모르는 값은 배송 상품 규칙이다 */
+export function fulfillmentRuleOf(type: string | null | undefined): FulfillmentRule {
+  return FULFILLMENT_RULES[fulfillmentTypeOf(type)];
+}
+
+/** 택배 배송이 필요한가 — 배송비 묶음·배송지·발송 흐름의 판정은 이 함수 하나를 지난다 */
+export function requiresShipping(type: string | null | undefined): boolean {
+  return fulfillmentRuleOf(type).requiresShipping;
+}
+
+/** 반품에 수거가 필요한가 — 비실물 반품은 수거 등록·수거 완료 없이 승인한다 */
+export function requiresCollection(type: string | null | undefined): boolean {
+  return fulfillmentRuleOf(type).requiresCollection;
+}
+
+/**
+ * 유효 제공 방식 — 요청 값이 유형에 허용되면 그 값, 생략이면 유형 기본값이다. 배송 상품은 null이다.
+ * 허용되지 않는 값은 `null`을 돌려주지 않고 호출부가 거부하도록 `undefined`를 돌려준다.
+ */
+export function resolveFulfillmentMode(
+  type: FulfillmentType,
+  mode: FulfillmentMode | null | undefined,
+): FulfillmentMode | null | undefined {
+  const rule = FULFILLMENT_RULES[type];
+  if (rule.modes.length === 0) return null;
+  if (mode === null || mode === undefined) return rule.defaultMode;
+  return rule.modes.includes(mode) ? mode : undefined;
+}
+
+/**
+ * 배송이 없는 주문상품의 배송 묶음 키 (`order_items.delivery_bundle_key`).
+ *
+ * null로 두면 환불 정산이 #29 이전 주문의 레거시 폴백(「묶음 = 같은 상품」, 상품의 **현재** 배송비)을 탄다.
+ * 이 키를 만나면 배송비 환불·차감이 0이고 `orders.delivery_fee_settlements`에 항목을 만들지 않는다.
+ * 정책 지문 키(`b:…`)와 겹치지 않는다.
+ */
+export const NO_SHIPPING_BUNDLE_KEY = "none";

package/src/schemas/misc.ts

@@ -147,6 +147,10 @@ export const eventTypeSchema = z
     "ORDER.PURCHASE_DECIDED",
     // 현재 발송하지 않음. 공개 계약 호환을 위해 값만 남겼다(구독해도 이벤트가 오지 않는다)
     "ORDER.ADDRESS_CHANGE_REQUESTED",
+    // 셀러 직권취소 (이슈 #50). 뒤에 붙여 기존 값의 순서를 바꾸지 않는다
+    "ORDER.CANCELED",
+    // 비실물 상품 제공 (이슈 #48). 구독한 수신자에게만 간다
+    "ORDER.FULFILLED",
     "CLAIM.CANCEL_REQUESTED",
     "CLAIM.RETURN_REQUESTED",
     "CLAIM.EXCHANGE_REQUESTED",
@@ -327,7 +331,9 @@ export const webhookDeliverySchema = z.object({
     .number()
     .int()
     .min(0)
-    .describe("지금까지의 시도 횟수. 최초 시도 1회 + 재시도 최대 4회"),
+    .describe(
+      "지금까지 전송을 시작한 횟수. 최초 시도 1회 + 재시도 최대 4회. 전송 도중 장애로 결과를 기록하지 못한 시도도 센다",
+    ),
   createdAt: z.string().describe("전송 기록이 적재된 일시 (ISO 8601)"),
   attemptedAt: z.string().nullable().describe("마지막 시도 일시 (ISO 8601). 미시도면 null"),
   nextAttemptAt: z

package/src/schemas/order.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
+import { orderItemDownloadSchema } from "./digital-asset";
+import { fulfillmentTypeResponseSchema } from "./fulfillment";
+import { MAX_CODE_LENGTH, orderItemCodeSchema } from "./fulfillment-code";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 
 export const orderSummarySchema = z.object({
@@ -30,6 +33,57 @@ export const shippingAddressSchema = z.object({
 
 export type ShippingAddress = z.infer<typeof shippingAddressSchema>;
 
+/** 비실물 주문상품의 제공 정보 (이슈 #48) */
+export const orderItemFulfillmentSchema = z.object({
+  status: z
+    .string()
+    .describe(
+      "제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  mode: z.string().nullable().describe("제공 방식. `AUTO`·`MANUAL`"),
+  fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
+  note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
+  codes: z
+    .array(orderItemCodeSchema)
+    .optional()
+    .default([])
+    .describe(
+      "코드 발급 상품에 배정한 코드의 가린 값. 평문은 싣지 않는다. 코드 상품이 아니면 빈 배열. 서버는 항상 싣는다",
+    ),
+  download: orderItemDownloadSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 싣지 않는다. 다른 유형은 null. 서버는 항상 싣는다",
+    ),
+  mail: z
+    .object({
+      status: z
+        .string()
+        .describe(
+          "제공 안내 메일 상태. 현재 값은 `PENDING`(보낼 예정)·`SENDING`·`SENT`·`FAILED`·`SKIPPED`(보내지 않음: 스토어 설정 꺼짐·받을 주소 없음)이고 값이 추가될 수 있다",
+        ),
+      sentAt: z.string().nullable(),
+      errorCode: z.string().nullable().describe("실패·건너뜀 사유 코드"),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("구매자에게 보낸 제공 안내 메일(이슈 #48). 기록이 없으면 null. 서버는 항상 싣는다"),
+});
+
+/** 제공 안내 메일 재발송 결과 */
+export const fulfillmentMailResendSchema = z.object({
+  mailStatus: z
+    .string()
+    .describe("재발송 뒤 메일 상태 — `SENT`·`PENDING`(곧 다시 보낸다)·`FAILED`·`SKIPPED`"),
+});
+
+export type FulfillmentMailResend = z.infer<typeof fulfillmentMailResendSchema>;
+
+export type OrderItemFulfillment = z.infer<typeof orderItemFulfillmentSchema>;
+
 export const orderItemSchema = z.object({
   orderItemId: z.string(),
   orderId: z.string(),
@@ -40,6 +94,13 @@ export const orderItemSchema = z.object({
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
   sellerCode: z.string().nullable(),
+  fulfillmentType: fulfillmentTypeResponseSchema
+    .optional()
+    .default("SHIPPING")
+    .describe(
+      "주문 시점 상품 유형. 현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. " +
+        "배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, `DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. 서버는 항상 싣는다",
+    ),
   quantity: z.number().int().describe("주문 수량"),
   canceledQuantity: z
     .number()
@@ -51,13 +112,39 @@ export const orderItemSchema = z.object({
     .describe("살아 있는 수량 (`quantity` − `canceledQuantity`). 0이면 주문상품이 전량 취소됐다"),
   unitPrice: z.number().int(),
   discountAmount: z.number().int(),
-  totalPrice: z.number().int().describe("주문상품 금액 (할인 반영 단가 × 주문 수량)"),
+  totalPrice: z
+    .number()
+    .int()
+    .describe("주문상품 금액 (즉시할인 반영 단가 × 주문 수량). 쿠폰 할인 전 금액이다"),
+  couponDiscountAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이 주문상품에 배분된 쿠폰 할인 — 상품 쿠폰 + 주문 쿠폰 배분. 실결제 금액은 `totalPrice − couponDiscountAmount`이고 " +
+        "취소·반품 환불은 실결제 금액을 수량 비율로 나눈다. 쿠폰이 없으면 0. 서버는 항상 싣는다",
+    ),
   hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
+  fulfillment: orderItemFulfillmentSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "비실물 상품의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. 코드 평문·파일 주소는 싣지 않는다. 서버는 항상 싣는다",
+    ),
   autoDecisionDate: z.string().nullable(),
   sellerMemo: z.string().nullable(),
   orderedAt: z.string(),
   lastChangedAt: z.string(),
   lastChangedType: changeTypeSchema,
+  withdrawalRestricted: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "청약철회 제한 주문상품인가(이슈 #48). 구매자가 결제 전에 동의했고 제공이 시작되면(다운로드·열람·이용 시작) 구매자 취소·반품을 받지 않는다. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -67,6 +154,21 @@ export const orderItemSchema = z.object({
 
 export type OrderItem = z.infer<typeof orderItemSchema>;
 
+/** 주문이 받은 쿠폰 한 장 (이슈 #47) */
+export const orderDiscountSchema = z.object({
+  couponId: z.string().describe("쿠폰 id"),
+  name: z.string().describe("주문 시점 쿠폰 이름"),
+  kind: z
+    .string()
+    .describe(
+      "쿠폰 종류. 현재 값은 `ORDER`(주문 쿠폰)·`PRODUCT`(상품 쿠폰)·`DELIVERY`(배송비 쿠폰)이고 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  discountAmount: z.number().int().describe("이 쿠폰의 할인액 (원)"),
+  issueId: z.string().nullable().describe("발급 쿠폰 id. 코드 입력형은 null"),
+});
+
+export type OrderDiscount = z.infer<typeof orderDiscountSchema>;
+
 export const orderSchema = z.object({
   orderId: z.string(),
   orderedAt: z.string(),
@@ -75,6 +177,13 @@ export const orderSchema = z.object({
     phone: z.string(),
     email: z.email().optional(),
   }),
+  requiresShipping: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "택배 배송이 필요한 주문상품이 있는가. false면 `shippingAddress`는 주문자 이름·연락처만 있고 주소는 빈 문자열이다. 서버는 항상 싣는다",
+    ),
   shippingAddress: shippingAddressSchema,
   payment: z.object({
     method: z
@@ -102,10 +211,38 @@ export const orderSchema = z.object({
           "그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. " +
           "현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다",
       ),
-    productAmount: z.number().int(),
-    deliveryFee: z.number().int(),
-    discountAmount: z.number().int(),
-    totalAmount: z.number().int(),
+    productAmount: z.number().int().describe("상품 금액 합 (즉시할인 반영, 쿠폰 전)"),
+    deliveryFee: z.number().int().describe("배송비 (쿠폰 전)"),
+    discountAmount: z
+      .number()
+      .int()
+      .describe(
+        "즉시할인 합 (정가 − 할인 단가) × 수량. 쿠폰 할인은 `couponDiscountAmount`로 따로 온다",
+      ),
+    couponDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("상품·주문 쿠폰 할인 합계. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    deliveryDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    discounts: z
+      .array(orderDiscountSchema)
+      .optional()
+      .default([])
+      .describe("주문이 받은 쿠폰. 쿠폰이 없으면 빈 배열. 서버는 항상 싣는다"),
+    totalAmount: z
+      .number()
+      .int()
+      .describe(
+        "결제 금액 = productAmount + deliveryFee − couponDiscountAmount − deliveryDiscountAmount. " +
+          "쿠폰이 없는 주문은 productAmount + deliveryFee다",
+      ),
     paidAt: z.string().nullable(),
     cashReceipt: cashReceiptSchema
       .nullable()
@@ -115,6 +252,14 @@ export const orderSchema = z.object({
         "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
       ),
   }),
+  withdrawalAgreedAt: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -159,6 +304,12 @@ export const orderListQuerySchema = z.object({
     .optional()
     .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
   keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+  fulfillmentType: z
+    .string()
+    .optional()
+    .describe(
+      "상품 유형 필터(이슈 #48) — 이 유형(`SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`)의 주문상품이 하나라도 있는 주문",
+    ),
   testPayment: testPaymentQuery,
   ...pageQuery,
   size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
@@ -187,6 +338,8 @@ export interface OrderListParams extends PageParams {
   orderedTo?: string;
   status?: z.infer<typeof orderItemStatusSchema>;
   keyword?: string;
+  /** 상품 유형 필터 — 이 유형의 주문상품이 하나라도 있는 주문(이슈 #48) */
+  fulfillmentType?: z.infer<typeof fulfillmentTypeResponseSchema>;
   /** 테스트 결제 필터 — `"true"` 테스트 결제만, `"false"` 실결제만, 생략하면 전부 */
   testPayment?: "true" | "false";
 }
@@ -345,13 +498,48 @@ export const cancelBySellerRequestSchema = z.object({
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 
+/**
+ * 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 수동 제공 비실물 주문상품(이용권·방문 수령 등)을
+ * 제공 완료(`DELIVERED`)로 바꾼다.
+ */
+export const fulfillRequestSchema = z.object({
+  note: z
+    .string()
+    .trim()
+    .max(1000)
+    .optional()
+    .describe("구매자에게 보일 이용 안내(예: 예약 방법, 수령 장소). 주문 상세에 실린다"),
+  codes: z
+    .array(z.string().trim().min(1).max(MAX_CODE_LENGTH))
+    .min(1)
+    .max(100)
+    .optional()
+    .describe(
+      "수동 제공 코드 발급 상품의 코드 — 셀러 시스템이 발급한 코드를 넘긴다. 남은 수량만큼 보낸다(`CODE_COUNT_MISMATCH`). " +
+        "암호화해 저장하고 구매자가 열람할 때만 평문으로 나간다. 다른 유형은 보내지 않는다",
+    ),
+});
+
+export type FulfillRequest = z.infer<typeof fulfillRequestSchema>;
+
+/** 제공 처리 일괄 요청 — `POST /v1/order-items/fulfill` */
+export const fulfillBulkRequestSchema = z.object({
+  orderItemIds: z.array(z.string()).min(1).max(100),
+  note: fulfillRequestSchema.shape.note,
+});
+
+export type FulfillBulkRequest = z.infer<typeof fulfillBulkRequestSchema>;
+
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 export const cancelBySellerResultSchema = z.object({
   orderItemId: z.string(),
   refundAmount: z
     .number()
     .int()
-    .describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감"),
+    .describe(
+      "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
+        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)",
+    ),
   quantity: z.number().int().describe("취소한 수량"),
   canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
   deliveryFeeRefundAmount: z
@@ -364,6 +552,18 @@ export const cancelBySellerResultSchema = z.object({
     .number()
     .int()
     .describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
+  couponChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+  couponChargeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
   refundedAt: z.string(),
 });