@sayren/store-sdk 0.17.0 → 0.19.0

package/package.json

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

package/src/client.ts

@@ -204,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,
@@ -234,6 +236,30 @@ import {
   updateMemberRoleRequestSchema,
   updateStoreRequestSchema,
 } from "./schemas/store";
+import {
+  type ChangeStorefrontSlugRequest,
+  type ChangeStorefrontTemplateRequest,
+  type CreateStorefrontPreviewLinkRequest,
+  type CreateStorefrontSiteRequest,
+  changeStorefrontSlugRequestSchema,
+  changeStorefrontTemplateRequestSchema,
+  createStorefrontPreviewLinkRequestSchema,
+  createStorefrontSiteRequestSchema,
+  type DisableStorefrontHostingRequest,
+  disableStorefrontHostingRequestSchema,
+  type PublishStorefrontVersionRequest,
+  publishStorefrontVersionRequestSchema,
+  type RollbackStorefrontRequest,
+  rollbackStorefrontRequestSchema,
+  type SetStorefrontVisibilityRequest,
+  setStorefrontVisibilityRequestSchema,
+  storefrontHostingSchema,
+  storefrontPreviewLinkSchema,
+  storefrontSiteSchema,
+  storefrontSlugAvailabilitySchema,
+  storefrontTemplateSchema,
+  storefrontVersionSchema,
+} from "./schemas/storefront-hosting";
 import {
   type UploadPurpose,
   type UploadRequest,
@@ -488,14 +514,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}`, {
@@ -1327,6 +1353,78 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("POST", path`/seller-addresses/${addressId}/default`),
     },
 
+    /**
+     * 스토어프론트 호스팅 (이슈 #53) — 조회 `storefront:r`, 쓰기 `storefront:rw`(OWNER·ADMIN).
+     * 쓰기 응답은 바뀐 사이트다. Cloudflare 반영은 커밋 뒤라 `provisioning.status`가 잠시 `PENDING`일 수 있다.
+     * 에이전트 토큰의 발행·되돌리기·템플릿 변경·공개 전환·슬러그 변경·끄기는 승인 대기(`ApprovalPendingError`)다.
+     */
+    storefront: {
+      /** `GET /v1/storefront/templates` — 템플릿 카탈로그 */
+      listTemplates: () =>
+        storeHttp.request("GET", "/storefront/templates", z.array(storefrontTemplateSchema)),
+      /** `GET /v1/storefront/site` — 스위치 상태와 현재 사이트(없으면 `site: null`) */
+      get: () => storeHttp.request("GET", "/storefront/site", storefrontHostingSchema),
+      /** `GET /v1/storefront/slug-availability?slug=` — 슬러그를 쓸 수 있는가 */
+      checkSlug: (slug: string) =>
+        storeHttp.request(
+          "GET",
+          "/storefront/slug-availability",
+          storefrontSlugAvailabilitySchema,
+          {
+            query: { slug },
+          },
+        ),
+      /** `POST /v1/storefront/site` (201) — 템플릿으로 사이트를 만들고 v1을 발행한다. 공개 상태는 오픈 준비 중이다 */
+      create: (body: CreateStorefrontSiteRequest) =>
+        storeHttp.request("POST", "/storefront/site", storefrontSiteSchema, {
+          body: createStorefrontSiteRequestSchema.parse(body),
+        }),
+      /** `POST /v1/storefront/site/template` — 템플릿을 바꾼다. 새 버전을 만들고 기본으로 곧바로 발행한다 */
+      changeTemplate: (body: ChangeStorefrontTemplateRequest) =>
+        storeHttp.request("POST", "/storefront/site/template", storefrontSiteSchema, {
+          body: changeStorefrontTemplateRequestSchema.parse(body),
+        }),
+      /** `GET /v1/storefront/site/versions` — 버전 목록(최신 먼저) */
+      listVersions: () =>
+        storeHttp.request("GET", "/storefront/site/versions", z.array(storefrontVersionSchema)),
+      /** `POST /v1/storefront/site/versions/{versionId}/publish` — 그 버전을 발행한다(이미 발행돼 있으면 그대로 200) */
+      publish: (versionId: string, body: PublishStorefrontVersionRequest = {}) =>
+        storeHttp.request(
+          "POST",
+          path`/storefront/site/versions/${versionId}/publish`,
+          storefrontSiteSchema,
+          { body: publishStorefrontVersionRequestSchema.parse(body) },
+        ),
+      /** `POST /v1/storefront/site/rollback` — 이전 발행 버전으로 되돌린다(재빌드 없음) */
+      rollback: (body: RollbackStorefrontRequest = {}) =>
+        storeHttp.request("POST", "/storefront/site/rollback", storefrontSiteSchema, {
+          body: rollbackStorefrontRequestSchema.parse(body),
+        }),
+      /** `PUT /v1/storefront/site/slug` — 슬러그를 바꾼다. 옛 슬러그는 90일 보류되고 새 주소로 301한다 */
+      changeSlug: (body: ChangeStorefrontSlugRequest) =>
+        storeHttp.request("PUT", "/storefront/site/slug", storefrontSiteSchema, {
+          body: changeStorefrontSlugRequestSchema.parse(body),
+        }),
+      /** `PUT /v1/storefront/site/visibility` — 오픈 준비 중 ↔ 공개 */
+      setVisibility: (body: SetStorefrontVisibilityRequest) =>
+        storeHttp.request("PUT", "/storefront/site/visibility", storefrontSiteSchema, {
+          body: setStorefrontVisibilityRequestSchema.parse(body),
+        }),
+      /**
+       * `POST /v1/storefront/site/preview-link` — 오픈 준비 중인 사이트를 구성원이 볼 수 있는 5분짜리 링크.
+       * 콘솔에서 로그인한 OWNER·ADMIN만 받는다
+       */
+      createPreviewLink: (body: CreateStorefrontPreviewLinkRequest = {}) =>
+        storeHttp.request("POST", "/storefront/site/preview-link", storefrontPreviewLinkSchema, {
+          body: createStorefrontPreviewLinkRequestSchema.parse(body),
+        }),
+      /** `POST /v1/storefront/site/disable` — 호스팅을 끈다(사이트 `CLOSED`, 슬러그 90일 보류). 다시 만들 수 있다 */
+      disable: (body: DisableStorefrontHostingRequest) =>
+        storeHttp.request("POST", "/storefront/site/disable", storefrontSiteSchema, {
+          body: disableStorefrontHostingRequestSchema.parse(body),
+        }),
+    },
+
     store: {
       get: () => storeHttp.request("GET", "/store", storeSchema),
       /**

package/src/index.ts

@@ -40,6 +40,7 @@ export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
 export * from "./schemas/shipping-policy";
 export * from "./schemas/store";
+export * from "./schemas/storefront-hosting";
 export * from "./schemas/telemetry";
 export * from "./schemas/upload";
 export * from "./schemas/webhook-event";

package/src/schemas/fulfillment.ts

@@ -143,3 +143,434 @@ export function resolveFulfillmentMode(
  * 정책 지문 키(`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/order.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
 import { orderItemDownloadSchema } from "./digital-asset";
-import { fulfillmentTypeResponseSchema } from "./fulfillment";
+import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 import { MAX_CODE_LENGTH, orderItemCodeSchema } from "./fulfillment-code";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 
@@ -94,13 +94,10 @@ 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`는 제공 완료(방문 수령은 수령 완료)다. 서버는 항상 싣는다",
-    ),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
+    "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, " +
+      "`DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. 상품을 나중에 고쳐도 바뀌지 않는다. 실제 제공 기록은 `fulfillment`에 있다",
+  ),
   quantity: z.number().int().describe("주문 수량"),
   canceledQuantity: z
     .number()
@@ -138,13 +135,6 @@ export const orderItemSchema = z.object({
   orderedAt: z.string(),
   lastChangedAt: z.string(),
   lastChangedType: changeTypeSchema,
-  withdrawalRestricted: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe(
-      "청약철회 제한 주문상품인가(이슈 #48). 구매자가 결제 전에 동의했고 제공이 시작되면(다운로드·열람·이용 시작) 구매자 취소·반품을 받지 않는다. 서버는 항상 싣는다",
-    ),
   testPayment: z
     .boolean()
     .describe(
@@ -339,7 +329,7 @@ export interface OrderListParams extends PageParams {
   status?: z.infer<typeof orderItemStatusSchema>;
   keyword?: string;
   /** 상품 유형 필터 — 이 유형의 주문상품이 하나라도 있는 주문(이슈 #48) */
-  fulfillmentType?: z.infer<typeof fulfillmentTypeResponseSchema>;
+  fulfillmentType?: string;
   /** 테스트 결제 필터 — `"true"` 테스트 결제만, `"false"` 실결제만, 생략하면 전부 */
   testPayment?: "true" | "false";
 }