@sayren/store-sdk 0.15.1 → 0.17.0

package/src/schemas/product.ts

@@ -1,6 +1,11 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
-import { refundPolicyPatchSchema } from "./refund-policy";
+import {
+  fulfillmentModeSchema,
+  fulfillmentTypeResponseSchema,
+  fulfillmentTypeSchema,
+} from "./fulfillment";
+import { productRefundPolicyPatchSchema } from "./refund-policy";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
@@ -27,6 +32,7 @@ export const productSummarySchema = z.object({
   thumbnailUrl: z.url().optional(),
   /** optionGroups.length > 0 */
   hasOptions: z.boolean(),
+  fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
   updatedAt: z.string(),
 });
 
@@ -73,6 +79,69 @@ export const productVariantSchema = z.object({
 
 export type ProductVariant = z.infer<typeof productVariantSchema>;
 
+export const discountSchema = z.object({
+  productId: z.string(),
+  discountType: z.enum(["RATE", "AMOUNT"]),
+  discountValue: z.number().int(),
+  discountedPrice: z.number().int(),
+  startAt: z.string().nullable(),
+  endAt: z.string().nullable(),
+});
+
+export type Discount = z.infer<typeof discountSchema>;
+
+/**
+ * 상품 유형 응답 필드 (이슈 #48) — 이 필드 이전 서버의 응답에는 없으므로 기본값을 둔다. 서버는 항상 싣는다.
+ */
+function productFulfillmentResponseShape() {
+  return {
+    fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
+    fulfillmentMode: z
+      .string()
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "제공 방식. `AUTO`(결제 확정과 함께 제공)·`MANUAL`(셀러가 제공 처리). 배송 상품은 null. 값이 추가될 수 있어 문자열로 받는다",
+      ),
+    stockTracking: z
+      .boolean()
+      .optional()
+      .default(true)
+      .describe("재고를 세는가. false면 재고와 무관하게 판다(파일 다운로드 기본)"),
+    downloadLimit: z
+      .number()
+      .int()
+      .nullable()
+      .optional()
+      .default(null)
+      .describe("파일 다운로드 횟수 한도. 파일 다운로드 상품이 아니면 null"),
+    downloadDays: z
+      .number()
+      .int()
+      .nullable()
+      .optional()
+      .default(null)
+      .describe("파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품이 아니면 null"),
+    withdrawalRestricted: z
+      .boolean()
+      .optional()
+      .default(false)
+      .describe(
+        "청약철회 제한 대상인가. 파일 다운로드·코드 발급 상품만 켤 수 있다(그 밖의 유형은 false로 저장한다). " +
+          "true면 주문서에서 제한 고지에 대한 구매자 동의를 받고, 첫 다운로드·열람 뒤 구매자 취소·반품을 받지 않는다",
+      ),
+    pickupAddressId: z
+      .string()
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "방문 수령지 주소 id(`seller_addresses`, 유형 PICKUP). 방문 수령 상품이 아니면 null",
+      ),
+  };
+}
+
 export const productSchema = productSummarySchema.extend({
   description: z.string().optional(),
   /**
@@ -91,12 +160,23 @@ export const productSchema = productSummarySchema.extend({
   conditionalFreeAmount: z.number().int().nullable().optional(),
   returnFee: z.number().int().optional(),
   exchangeFee: z.number().int().optional(),
-  refundPolicy: refundPolicyPatchSchema
+  refundPolicy: productRefundPolicyPatchSchema
     .nullable()
     .optional()
     .describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
   shippingAddressId: z.string().nullable().optional(),
   returnAddressId: z.string().nullable().optional(),
+  ...productFulfillmentResponseShape(),
+  /**
+   * 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
+   * 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
+   */
+  discount: discountSchema
+    .nullable()
+    .optional()
+    .describe(
+      "설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null",
+    ),
   createdAt: z.string().optional(),
 });
 
@@ -281,6 +361,68 @@ const ADDRESS_DESCRIPTIONS = {
     "이 스토어의 `RETURN` 주소가 아니면 거부한다",
 } as const;
 
+/**
+ * 상품 유형 요청 필드 (이슈 #48) — 등록·전체 수정·부분 수정이 같은 필드를 받는다.
+ *
+ * 생략의 뜻: 등록은 배송 상품(`SHIPPING`)과 유형 기본값이고, 전체 수정(PUT)·부분 수정(PATCH)은 **현재 값을 유지**한다.
+ * 이 필드를 모르는 옛 클라이언트가 전체 수정을 보내도 유형이 배송 상품으로 되돌아가지 않게 한다.
+ */
+function productFulfillmentRequestShape() {
+  return {
+    fulfillmentType: fulfillmentTypeSchema
+      .optional()
+      .describe(
+        "상품 유형. `SHIPPING` 배송 상품 · `DOWNLOAD` 파일 다운로드 · `CODE` 코드 발급 · `SERVICE` 이용권·서비스 · `PICKUP` 방문 수령. " +
+          "등록에서 생략하면 SHIPPING이고, 수정에서 생략하면 바꾸지 않는다. 판매 이력이 있는 상품의 유형은 바꿀 수 없다" +
+          "(409 `FULFILLMENT_TYPE_LOCKED`). 배송 상품이 아니면 배송비·출고지·반품지·반품비·교환비를 무시하고 0·null로 저장한다",
+      ),
+    fulfillmentMode: fulfillmentModeSchema
+      .nullable()
+      .optional()
+      .describe(
+        "제공 방식. `AUTO` 결제 확정과 함께 제공 · `MANUAL` 셀러가 제공 처리. 생략·null이면 유형 기본값이다" +
+          "(코드 발급 AUTO, 이용권 MANUAL, 파일 다운로드 AUTO만, 방문 수령 MANUAL만). 배송 상품은 무시한다",
+      ),
+    stockTracking: z
+      .boolean()
+      .optional()
+      .describe(
+        "재고를 세는가. 파일 다운로드 상품만 끌 수 있다(기본 false). 그 밖의 유형은 항상 true",
+      ),
+    downloadLimit: z
+      .number()
+      .int()
+      .min(1)
+      .max(100)
+      .nullable()
+      .optional()
+      .describe("파일 다운로드 횟수 한도. 파일 다운로드 상품만 쓰고 생략·null이면 5회"),
+    downloadDays: z
+      .number()
+      .int()
+      .min(1)
+      .max(3650)
+      .nullable()
+      .optional()
+      .describe(
+        "파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품만 쓰고 생략·null이면 30일",
+      ),
+    withdrawalRestricted: z
+      .boolean()
+      .optional()
+      .describe(
+        "청약철회 제한 대상인가. true면 주문서가 제한 고지를 보여 주고 구매자 동의를 받는다. 배송 상품은 false로 저장한다",
+      ),
+    pickupAddressId: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "방문 수령지 주소 id(`GET /v1/seller-addresses?type=PICKUP`). 방문 수령 상품만 쓴다. 생략하면 스토어 기본 방문 수령지를 저장한다",
+      ),
+  };
+}
+
 export const productCreateRequestSchema = z
   .object({
     name: z.string().min(1).max(100),
@@ -332,7 +474,7 @@ export const productCreateRequestSchema = z
       .int()
       .default(0)
       .describe("교환 배송비. 원 단위. `refundPolicy.exchangeDeliveryFee`와 같은 값이다"),
-    refundPolicy: refundPolicyPatchSchema
+    refundPolicy: productRefundPolicyPatchSchema
       .nullish()
       .describe(
         "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
@@ -340,6 +482,7 @@ export const productCreateRequestSchema = z
       ),
     shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.shipping),
     returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return),
+    ...productFulfillmentRequestShape(),
   })
   .extend(optionModelRequestSchema.shape);
 
@@ -358,6 +501,7 @@ export const productPatchRequestSchema = z
       .optional()
       .describe(ADDRESS_DESCRIPTIONS.patchShipping),
     returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn),
+    ...productFulfillmentRequestShape(),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -396,17 +540,6 @@ export const productListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
-export const discountSchema = z.object({
-  productId: z.string(),
-  discountType: z.enum(["RATE", "AMOUNT"]),
-  discountValue: z.number().int(),
-  discountedPrice: z.number().int(),
-  startAt: z.string().nullable(),
-  endAt: z.string().nullable(),
-});
-
-export type Discount = z.infer<typeof discountSchema>;
-
 export const discountRequestSchema = z.object({
   discountType: z.enum(["RATE", "AMOUNT"]),
   discountValue: z.number().int().min(1),