@sayren/store-sdk 0.16.0 → 0.18.0

package/src/schemas/fulfillment.ts

@@ -0,0 +1,576 @@
+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";
+
+// ─── 상품 이행 (이슈 #57) ─────────────────────────────────────
+//
+// 상품은 공통 필드 + `fulfillment` 판별 유니온이다. 유형 키 안에 그 유형의 속성만 있다(서버는 `product_{type}` 1:1 테이블).
+// - 요청은 닫힌 유니온이다. 모르는 `type`·다른 유형의 키·오타는 400이다(`strictObject`).
+// - 등록은 유형 안 필드에 기본값이 있다. 수정(PUT·PATCH)은 `fulfillment`를 통째로 받고 **유형 안 필드가 모두 필수다** —
+//   통째 교체에 기본값을 두면 부분 수정이 출고지·청약철회 제한을 조용히 되돌린다.
+// - 응답은 열린 유니온이다. 서버가 유형을 더해도(#56 `RESERVATION`) SDK가 깨지지 않게 모르는 유형은
+//   `{ type: "OTHER", rawType }`로 읽는다. 알려진 유형의 모양이 틀리면 파싱 오류다.
+
+/** 배송비 유형 — 무료·유료·조건부 무료 */
+export const deliveryTypeSchema = z.enum(["FREE", "PAID", "CONDITIONAL_FREE"]);
+
+export type DeliveryType = z.infer<typeof deliveryTypeSchema>;
+
+/** 파일 다운로드 기본값 — 횟수 5회·기간 30일(#48 결정 8) */
+export const DOWNLOAD_DEFAULTS = { limit: 5, days: 30 } as const;
+
+const KNOWN_FULFILLMENT_TYPES: readonly string[] = fulfillmentTypeSchema.options;
+
+const ADDRESS_ID_DESCRIPTIONS = {
+  shipping:
+    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 등록에서 생략하면 그 시점 스토어 기본 출고지를 저장한다. " +
+    "`null`이면 비워 둔다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+  return:
+    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 등록에서 생략하면 그 시점 스토어 기본 반품지를 저장한다. " +
+    "`null`이면 비워 둔다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다",
+  pickup:
+    "방문 수령지 주소 id(`GET /v1/seller-addresses?type=PICKUP`). 등록에서 생략하면 그 시점 스토어 기본 방문 수령지를 저장하고, " +
+    "기본 방문 수령지도 없으면 400 `PICKUP_ADDRESS_REQUIRED`다. 이 스토어의 `PICKUP` 주소가 아니면 거부한다",
+} as const;
+
+/**
+ * 배송비 필드 사이의 일관성 — FREE의 배송비, 조건부 무료가 아닌 상품의 무료 기준을 조용히 0·null로 바꿔 저장하지 않고 400으로 돌려준다
+ * (셀러가 저장됐다고 믿는 값이 사라지지 않게). 조건부 무료는 기준 금액이 필수다 — 기준 없는 조건부 무료는 계산상 유료 배송이다.
+ */
+function refineShippingConsistency(
+  value: { deliveryType: string; deliveryFee?: number; conditionalFreeAmount?: number | null },
+  ctx: z.RefinementCtx,
+) {
+  if (value.deliveryType === "FREE" && value.deliveryFee !== undefined && value.deliveryFee !== 0) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["deliveryFee"],
+      message: "무료 배송(FREE)의 배송비는 0이거나 생략해야 합니다",
+    });
+  }
+  const threshold = value.conditionalFreeAmount;
+  const hasThreshold = threshold !== undefined && threshold !== null;
+  if (value.deliveryType === "CONDITIONAL_FREE" && !hasThreshold) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["conditionalFreeAmount"],
+      message: "조건부 무료(CONDITIONAL_FREE)는 무료 기준 금액이 필요합니다",
+    });
+  }
+  if (value.deliveryType !== "CONDITIONAL_FREE" && hasThreshold) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["conditionalFreeAmount"],
+      message: "무료 기준 금액은 조건부 무료(CONDITIONAL_FREE)에서만 받습니다",
+    });
+  }
+}
+
+const deliveryTypeDescription =
+  "배송비 유형. `FREE` 무료, `PAID` 유료, `CONDITIONAL_FREE` 조건부 무료";
+
+// ── 등록 요청 ──
+
+const shippingCreateSchema = z
+  .strictObject({
+    deliveryType: deliveryTypeSchema.default("PAID").describe(deliveryTypeDescription),
+    deliveryFee: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "배송비. 원 단위. 생략하면 스토어 기본 배송비(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 저장한다. FREE면 0이거나 생략한다",
+      ),
+    conditionalFreeAmount: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .optional()
+      .describe("무료 배송이 되는 묶음 소계. 원 단위. CONDITIONAL_FREE에서만 받고 필수다"),
+    shippingAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
+    returnAddressId: z.string().nullable().optional().describe(ADDRESS_ID_DESCRIPTIONS.return),
+  })
+  .superRefine(refineShippingConsistency);
+
+const downloadCreateSchema = z.strictObject({
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .default(DOWNLOAD_DEFAULTS.limit)
+    .describe("다운로드 횟수 한도(수량 1개당). 생략하면 5회"),
+  days: z
+    .number()
+    .int()
+    .min(1)
+    .max(3650)
+    .default(DOWNLOAD_DEFAULTS.days)
+    .describe("다운로드 기간(제공일부터 일수). 생략하면 30일"),
+  stockTracking: z
+    .boolean()
+    .default(false)
+    .describe("재고를 세는가. 생략하면 false(재고와 무관하게 판다)"),
+  withdrawalRestricted: z
+    .boolean()
+    .default(false)
+    .describe(
+      "청약철회 제한 대상인가. true면 주문서가 제한 고지 동의를 받고, 첫 다운로드 뒤 구매자 단순 변심 취소·반품을 받지 않는다",
+    ),
+});
+
+const codeCreateSchema = z.strictObject({
+  mode: fulfillmentModeSchema
+    .default("AUTO")
+    .describe(
+      "제공 방식. `AUTO`는 코드 풀에서 결제 확정과 함께 배정하고, `MANUAL`은 셀러가 제공 처리 때 코드를 넘긴다",
+    ),
+  withdrawalRestricted: z
+    .boolean()
+    .default(false)
+    .describe("청약철회 제한 대상인가. true면 첫 열람 뒤 구매자 단순 변심 취소·반품을 받지 않는다"),
+});
+
+const serviceCreateSchema = z.strictObject({
+  mode: fulfillmentModeSchema
+    .default("MANUAL")
+    .describe("제공 방식. `AUTO`는 결제 확정과 함께 제공 완료, `MANUAL`은 셀러가 제공 처리한다"),
+});
+
+const pickupCreateSchema = z.strictObject({
+  addressId: z.string().optional().describe(ADDRESS_ID_DESCRIPTIONS.pickup),
+});
+
+/**
+ * 상품 이행 — 등록(POST). 유형 키를 생략하면 그 유형의 기본값이다(`{ "type": "DOWNLOAD" }`만으로 등록할 수 있다).
+ */
+export const productFulfillmentCreateSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("SHIPPING"), shipping: shippingCreateSchema.optional() }),
+  z.strictObject({
+    type: z.literal("DOWNLOAD"),
+    download: downloadCreateSchema.default({
+      limit: DOWNLOAD_DEFAULTS.limit,
+      days: DOWNLOAD_DEFAULTS.days,
+      stockTracking: false,
+      withdrawalRestricted: false,
+    }),
+  }),
+  z.strictObject({
+    type: z.literal("CODE"),
+    code: codeCreateSchema.default({ mode: "AUTO", withdrawalRestricted: false }),
+  }),
+  z.strictObject({
+    type: z.literal("SERVICE"),
+    service: serviceCreateSchema.default({ mode: "MANUAL" }),
+  }),
+  z.strictObject({ type: z.literal("PICKUP"), pickup: pickupCreateSchema.default({}) }),
+]);
+
+export type ProductFulfillmentCreate = z.infer<typeof productFulfillmentCreateSchema>;
+/** 등록 요청의 입력 모양 — 기본값이 채워지기 전(생략 가능한 필드가 optional) */
+export type ProductFulfillmentCreateInput = z.input<typeof productFulfillmentCreateSchema>;
+
+// ── 수정 요청 ──
+
+const shippingUpdateSchema = z
+  .strictObject({
+    deliveryType: deliveryTypeSchema.describe(deliveryTypeDescription),
+    deliveryFee: z.number().int().min(0).describe("배송비. 원 단위. FREE면 0"),
+    conditionalFreeAmount: z
+      .number()
+      .int()
+      .min(0)
+      .nullable()
+      .describe("무료 배송이 되는 묶음 소계. CONDITIONAL_FREE면 필수, 아니면 null"),
+    shippingAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.shipping),
+    returnAddressId: z.string().nullable().describe(ADDRESS_ID_DESCRIPTIONS.return),
+  })
+  .superRefine(refineShippingConsistency);
+
+/**
+ * 상품 이행 — 수정(PUT·PATCH). 통째 교체이고 유형 키와 그 안의 필드가 **모두 필수**다. 서버는 현재 값과 병합하지 않는다.
+ * `fulfillment` 자체를 생략하면 이행을 바꾸지 않는다.
+ */
+export const productFulfillmentUpdateSchema = z.discriminatedUnion("type", [
+  z.strictObject({ type: z.literal("SHIPPING"), shipping: shippingUpdateSchema }),
+  z.strictObject({
+    type: z.literal("DOWNLOAD"),
+    download: z.strictObject({
+      limit: z.number().int().min(1).max(100),
+      days: z.number().int().min(1).max(3650),
+      stockTracking: z.boolean(),
+      withdrawalRestricted: z.boolean(),
+    }),
+  }),
+  z.strictObject({
+    type: z.literal("CODE"),
+    code: z.strictObject({ mode: fulfillmentModeSchema, withdrawalRestricted: z.boolean() }),
+  }),
+  z.strictObject({
+    type: z.literal("SERVICE"),
+    service: z.strictObject({ mode: fulfillmentModeSchema }),
+  }),
+  z.strictObject({
+    type: z.literal("PICKUP"),
+    pickup: z.strictObject({ addressId: z.string().describe(ADDRESS_ID_DESCRIPTIONS.pickup) }),
+  }),
+]);
+
+export type ProductFulfillmentUpdate = z.infer<typeof productFulfillmentUpdateSchema>;
+
+// ── 응답(저장된 값) ──
+
+/**
+ * 저장된 상품 이행 — 알려진 유형의 닫힌 유니온. 서버의 상품 엔티티와 응답이 이 모양을 쓴다.
+ * 응답 파싱은 `productFulfillmentResponseSchema`(열린 유니온)를 쓴다.
+ */
+export const productFulfillmentSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("SHIPPING"),
+    shipping: z.object({
+      deliveryType: deliveryTypeSchema,
+      deliveryFee: z.number().int().describe("배송비. 원 단위. FREE면 0"),
+      conditionalFreeAmount: z
+        .number()
+        .int()
+        .nullable()
+        .describe("조건부 무료 기준 묶음 소계. CONDITIONAL_FREE가 아니면 null"),
+      shippingAddressId: z
+        .string()
+        .nullable()
+        .describe("출고지 주소 id. null이면 스토어 기본 출고지를 따른다"),
+      returnAddressId: z
+        .string()
+        .nullable()
+        .describe("반품지 주소 id. null이면 스토어 기본 반품지를 따른다"),
+    }),
+  }),
+  z.object({
+    type: z.literal("DOWNLOAD"),
+    download: z.object({
+      limit: z.number().int().describe("다운로드 횟수 한도(수량 1개당)"),
+      days: z.number().int().describe("다운로드 기간(제공일부터 일수)"),
+      stockTracking: z.boolean().describe("재고를 세는가"),
+      withdrawalRestricted: z.boolean().describe("청약철회 제한 대상인가"),
+    }),
+  }),
+  z.object({
+    type: z.literal("CODE"),
+    code: z.object({
+      mode: fulfillmentModeSchema.describe("제공 방식"),
+      withdrawalRestricted: z.boolean().describe("청약철회 제한 대상인가"),
+    }),
+  }),
+  z.object({
+    type: z.literal("SERVICE"),
+    service: z.object({ mode: fulfillmentModeSchema.describe("제공 방식") }),
+  }),
+  z.object({
+    type: z.literal("PICKUP"),
+    pickup: z.object({
+      addressId: z
+        .string()
+        .nullable()
+        .describe(
+          "방문 수령지 주소 id. null은 수령지가 지워진 상품이다(수령지를 다시 지정할 때까지 팔 수 없다)",
+        ),
+    }),
+  }),
+]);
+
+export type ProductFulfillment = z.infer<typeof productFulfillmentSchema>;
+
+/** 유형 이름 → 그 유형의 저장된 이행 */
+export type ProductFulfillmentOf<T extends FulfillmentType> = Extract<
+  ProductFulfillment,
+  { type: T }
+>;
+
+/** 응답이 알려 주는 모르는 유형 — SDK가 아직 모르는 유형(서버가 나중에 더한 유형) */
+export interface UnknownFulfillment {
+  type: "OTHER";
+  /** 서버가 보낸 유형 이름 */
+  rawType: string;
+}
+
+/**
+ * 열린 응답 유니온 — 알려진 유형은 판별 유니온으로 검사하고, **모르는 유형만** `{ type: "OTHER", rawType }`로 읽는다.
+ *
+ * `type: z.string()` 가지를 그대로 두면 TS가 `type === "SHIPPING"`으로 좁혀도 문자열 가지가 남는다. `OTHER` 리터럴로 바꿔 좁히기를
+ * 지킨다. 알려진 유형의 모양이 틀린 응답은 폴백으로 숨기지 않고 파싱 오류로 둔다.
+ */
+export function openFulfillmentUnion<T extends z.ZodType>(known: T) {
+  return z.union([
+    known,
+    z
+      .looseObject({
+        type: z.string().refine((type) => !KNOWN_FULFILLMENT_TYPES.includes(type), {
+          message: "알려진 유형은 해당 유형의 모양이어야 합니다",
+        }),
+      })
+      .transform((value): UnknownFulfillment => ({ type: "OTHER", rawType: value.type })),
+  ]);
+}
+
+export const productFulfillmentResponseSchema = openFulfillmentUnion(
+  productFulfillmentSchema,
+).describe(
+  '상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 값이 추가될 수 있어 SDK는 모르는 유형을 `{ type: "OTHER", rawType }`로 읽는다',
+);
+
+export type ProductFulfillmentView = z.infer<typeof productFulfillmentResponseSchema>;
+
+// ── 판정 헬퍼 ──
+
+/** 제공 방식 — CODE·SERVICE는 저장된 값, DOWNLOAD는 AUTO, PICKUP은 MANUAL, 배송 상품은 null */
+export function fulfillmentModeOf(fulfillment: ProductFulfillment): FulfillmentMode | null {
+  switch (fulfillment.type) {
+    case "CODE":
+      return fulfillment.code.mode;
+    case "SERVICE":
+      return fulfillment.service.mode;
+    default:
+      return FULFILLMENT_RULES[fulfillment.type].defaultMode;
+  }
+}
+
+/** 재고를 세는가 — 파일 다운로드만 끌 수 있다 */
+export function stockTrackingOf(fulfillment: ProductFulfillment): boolean {
+  return fulfillment.type === "DOWNLOAD" ? fulfillment.download.stockTracking : true;
+}
+
+/** 청약철회 제한 대상인가 — 파일 다운로드·코드 발급만 켤 수 있다(전자상거래법 제17조 제2항 제5호, 디지털 콘텐츠) */
+export function withdrawalRestrictedOf(fulfillment: ProductFulfillment): boolean {
+  if (fulfillment.type === "DOWNLOAD") return fulfillment.download.withdrawalRestricted;
+  if (fulfillment.type === "CODE") return fulfillment.code.withdrawalRestricted;
+  return false;
+}
+
+/** 코드 풀을 쓰는가 — 코드 발급 + 자동 제공. 재고가 판매 가능 코드 수다 */
+export function usesCodePool(fulfillment: ProductFulfillment): boolean {
+  return fulfillment.type === "CODE" && fulfillment.code.mode === "AUTO";
+}
+
+/** 결제 확정과 함께 제공까지 끝내는가 — 비실물 + 자동 제공 */
+export function autoFulfillableOf(fulfillment: ProductFulfillment): boolean {
+  return (
+    !FULFILLMENT_RULES[fulfillment.type].requiresShipping &&
+    fulfillmentModeOf(fulfillment) === "AUTO"
+  );
+}
+
+// ─── 주문상품 이행 스냅샷 (이슈 #57) ─────────────────────────────
+
+/**
+ * 주문상품의 주문 시점 이행 — 결제 확정이 주문서 줄에서 굳힌다. 상품의 현재 값이 아니다. 서버는 주문상품 컬럼
+ * (`fulfillment_type`·`delivery_bundle_key`·`stock_tracked`·`withdrawal_restricted`)과 jsonb(`fulfillment_snapshot`)를 합쳐 이 모양을 만든다.
+ *
+ * `mode`는 **주문 시점 상품의 방식**이다. 실제 제공 방식은 제공 기록(`fulfillment.mode`)에 있고 다를 수 있다(자동 제공 상품의 수동 복구).
+ */
+export const orderItemFulfillmentSnapshotSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("SHIPPING"),
+    shipping: z.object({
+      bundleKey: z
+        .string()
+        .nullable()
+        .describe(
+          "배송 묶음 키. 같은 키의 주문상품이 배송비를 한 번 낸 한 묶음이다. #29 이전 주문은 null",
+        ),
+      returnAddressId: z
+        .string()
+        .nullable()
+        .describe(
+          "주문 시점 반품지 주소 id. null이거나 지워진 주소면 스토어 기본 반품지로 안내한다",
+        ),
+    }),
+  }),
+  z.object({
+    type: z.literal("DOWNLOAD"),
+    download: z.object({
+      limit: z.number().int().describe("주문 시점 다운로드 횟수 한도(수량 1개당)"),
+      days: z.number().int().describe("주문 시점 다운로드 기간(제공일부터 일수)"),
+      stockTracked: z.boolean().describe("주문 시점에 재고를 뺐는가"),
+      withdrawalRestricted: z
+        .boolean()
+        .describe("구매자가 제한 고지에 동의한 청약철회 제한 주문상품인가"),
+    }),
+  }),
+  z.object({
+    type: z.literal("CODE"),
+    code: z.object({
+      mode: z.string().describe("주문 시점 상품의 제공 방식. 현재 값은 `AUTO`·`MANUAL`"),
+      withdrawalRestricted: z
+        .boolean()
+        .describe("구매자가 제한 고지에 동의한 청약철회 제한 주문상품인가"),
+    }),
+  }),
+  z.object({
+    type: z.literal("SERVICE"),
+    service: z.object({
+      mode: z.string().describe("주문 시점 상품의 제공 방식. 현재 값은 `AUTO`·`MANUAL`"),
+    }),
+  }),
+  z.object({
+    type: z.literal("PICKUP"),
+    pickup: z.object({
+      addressId: z.string().nullable().describe("주문 시점 방문 수령지 주소 id"),
+    }),
+  }),
+]);
+
+export type OrderItemFulfillmentSnapshot = z.infer<typeof orderItemFulfillmentSnapshotSchema>;
+
+export const orderItemFulfillmentSnapshotResponseSchema = openFulfillmentUnion(
+  orderItemFulfillmentSnapshotSchema,
+).describe(
+  "주문 시점 이행 스냅샷. 상품을 나중에 고쳐도 바뀌지 않는다. 실제 제공 기록은 `fulfillment`에 있다. 값이 추가될 수 있어 SDK는 모르는 유형을 `OTHER`로 읽는다",
+);
+
+export type OrderItemFulfillmentSnapshotView = z.infer<
+  typeof orderItemFulfillmentSnapshotResponseSchema
+>;

package/src/schemas/misc.ts

@@ -149,6 +149,8 @@ export const eventTypeSchema = z
     "ORDER.ADDRESS_CHANGE_REQUESTED",
     // 셀러 직권취소 (이슈 #50). 뒤에 붙여 기존 값의 순서를 바꾸지 않는다
     "ORDER.CANCELED",
+    // 비실물 상품 제공 (이슈 #48). 구독한 수신자에게만 간다
+    "ORDER.FULFILLED",
     "CLAIM.CANCEL_REQUESTED",
     "CLAIM.RETURN_REQUESTED",
     "CLAIM.EXCHANGE_REQUESTED",
@@ -329,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