@sayren/store-sdk 0.8.0 → 0.10.0

package/src/schemas/store.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { storeRoleSchema } from "./auth";
+import { refundPolicyPatchSchema, refundPolicySchema } from "./refund-policy";
 
 /**
  * 스토어 코드 규칙 — 스토어프론트 API가 테넌트를 가르는 값이다(`X-Store-Code` 헤더).
@@ -102,6 +103,38 @@ export const analyticsOriginSchema = z
 /** 허용 오리진 상한 */
 export const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 
+/** 자동 배송완료·자동 구매확정 대기일 상한 */
+export const MAX_AUTO_TRANSITION_DAYS = 30;
+
+/**
+ * 약관 버전 — 스토어가 정하는 문자열이다(`1`·`2`·`2026-09-26`·`v1.2` 등). 형식은 강제하지 않고 값이 다르면 다른 버전이다.
+ * 올리면 그 약관에 동의한 구매자의 `reconsentRequired`가 켜지고, 재동의가 이력에 남는다. 되돌리면 재동의 요구도 풀린다.
+ */
+export const policyVersionSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(20)
+  .describe("약관 버전 문자열(1~20자). 예: `1`, `2026-09-26`");
+
+/**
+ * 약관 문서 주소 — 구매자에게 보여 주는 약관 본문의 주소다. 동의 시점 값이 이력 행에 복사되므로
+ * 나중에 주소를 바꿔도 "무엇에 동의했는지"가 남는다. `null`로 지울 수 있다.
+ */
+export const policyDocumentUrlSchema = z
+  .url()
+  .max(500)
+  .refine((value) => value.startsWith("https://"), "https 주소만 쓸 수 있어요")
+  .nullable();
+
+const autoDeliverDaysDescription =
+  "발송 후 자동 배송완료까지의 일수(0~30, 기본 7). 발송(`DISPATCHED`)·배송중(`DELIVERING`) 주문상품을 " +
+  "이 기간이 지나면 배송완료(`DELIVERED`)로 바꾼다. `0`이면 자동 배송완료를 하지 않는다";
+
+const autoConfirmDaysDescription =
+  "배송완료 후 자동 구매확정까지의 일수(0~30, 기본 7). 배송완료 시점에 구매확정 예정일(`autoDecisionDate`)을 이 값으로 잡고, " +
+  "그 날짜가 지나면 구매확정(`PURCHASE_DECIDED`)으로 바꾼다. 진행 중인 클레임이 있으면 건너뛴다. `0`이면 자동 구매확정을 하지 않는다";
+
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
 export const updateStoreRequestSchema = z
   .object({
@@ -132,6 +165,41 @@ export const updateStoreRequestSchema = z
         "비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. " +
           "장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다",
       ),
+    autoDeliverDays: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_AUTO_TRANSITION_DAYS)
+      .optional()
+      .describe(autoDeliverDaysDescription),
+    autoConfirmDays: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_AUTO_TRANSITION_DAYS)
+      .optional()
+      .describe(autoConfirmDaysDescription),
+    refundPolicy: refundPolicyPatchSchema
+      .optional()
+      .describe(
+        "스토어 기본 환불 정책 — 준 항목만 바꾼다. 상품별 정책(`products.refundPolicy`)이 없는 상품에 적용된다",
+      ),
+    termsVersion: policyVersionSchema
+      .optional()
+      .describe(
+        "이용약관 버전. 올리면 이 약관에 동의한 구매자에게 재동의를 요구한다(`GET /storefront/v1/me`의 `reconsentRequired`)",
+      ),
+    privacyVersion: policyVersionSchema
+      .optional()
+      .describe("개인정보 수집이용 동의 버전. 올리면 구매자에게 재동의를 요구한다"),
+    termsUrl: policyDocumentUrlSchema
+      .optional()
+      .describe(
+        "이용약관 문서 주소(https). 동의 시점의 값이 동의 이력에 복사된다. `null`을 주면 지운다",
+      ),
+    privacyUrl: policyDocumentUrlSchema
+      .optional()
+      .describe("개인정보 수집이용 동의 문서 주소(https). `null`을 주면 지운다"),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -156,6 +224,23 @@ export const storeSchema = z.object({
       "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+  autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
+  autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
+  refundPolicy: refundPolicySchema.describe(
+    "스토어 기본 환불 정책. 스토어가 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다",
+  ),
+  termsVersion: z.string().describe("현재 이용약관 버전. 가입·재동의가 이 값으로 이력에 남는다"),
+  privacyVersion: z.string().describe("현재 개인정보 수집이용 동의 버전"),
+  termsVersionUpdatedAt: z
+    .string()
+    .nullable()
+    .describe("이용약관 버전을 마지막으로 바꾼 시각. 바꾼 적이 없으면 null"),
+  privacyVersionUpdatedAt: z.string().nullable(),
+  termsUrl: z
+    .string()
+    .nullable()
+    .describe("이용약관 문서 주소. 정하지 않았으면 null이고 동의 이력에도 주소가 남지 않는다"),
+  privacyUrl: z.string().nullable().describe("개인정보 수집이용 동의 문서 주소"),
   memberCount: z.number().int(),
   createdAt: z.string(),
 });

package/src/schemas/upload.ts

@@ -1,5 +1,82 @@
 import { z } from "zod";
 
+/**
+ * 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
+ *
+ * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
+ * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+ */
+export const uploadPurposeSchema = z.enum(["product-image", "description"]);
+
+export type UploadPurpose = z.infer<typeof uploadPurposeSchema>;
+
+export interface UploadPurposeLimit {
+  /** 소문자 확장자 목록 */
+  extensions: readonly string[];
+  maxBytes: number;
+}
+
+const MB = 1024 * 1024;
+
+/**
+ * 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
+ *
+ * 크기는 **요청이 스스로 신고한 값**으로만 검사한다. 바이트는 api를 거치지 않고 CDN으로
+ * 직접 PUT되므로 이 검사는 셀러가 올리기 전에 알게 하는 장치이고, 실제 상한은 CDN이 강제한다.
+ */
+export const UPLOAD_PURPOSE_LIMITS: Record<UploadPurpose, UploadPurposeLimit> = {
+  // svg는 스크립트를 품을 수 있고, 동영상은 목록 썸네일 자리에 쓸 수 없다
+  "product-image": {
+    extensions: ["jpg", "jpeg", "png", "webp", "avif", "gif"],
+    maxBytes: 10 * MB,
+  },
+  description: {
+    extensions: ["jpg", "jpeg", "png", "gif", "webp", "avif", "svg", "mp4", "webm", "mov"],
+    maxBytes: 50 * MB,
+  },
+};
+
+/** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
+export function uploadExtensionOf(filename: string): string {
+  const dot = filename.lastIndexOf(".");
+  if (dot < 0 || dot === filename.length - 1) return "";
+  return filename.slice(dot + 1).toLowerCase();
+}
+
+export interface UploadRejection {
+  /** 400 형식 불일치 / 413 크기 초과 */
+  status: 400 | 413;
+  code: "UNSUPPORTED_FILE_TYPE" | "FILE_TOO_LARGE";
+  message: string;
+}
+
+/**
+ * 용도 제한 위반 여부. 통과하면 `null`.
+ * 서버가 던지는 오류와 콘솔이 먼저 띄우는 안내가 갈리지 않도록 한 함수로 판정한다.
+ */
+export function uploadRejection(
+  purpose: UploadPurpose,
+  filename: string,
+  size?: number,
+): UploadRejection | null {
+  const limit = UPLOAD_PURPOSE_LIMITS[purpose];
+  if (!limit.extensions.includes(uploadExtensionOf(filename))) {
+    return {
+      status: 400,
+      code: "UNSUPPORTED_FILE_TYPE",
+      message: `지원하지 않는 파일 형식입니다. ${limit.extensions.join(", ")}만 올릴 수 있습니다`,
+    };
+  }
+  if (size !== undefined && size > limit.maxBytes) {
+    return {
+      status: 413,
+      code: "FILE_TOO_LARGE",
+      message: `파일이 너무 큽니다. ${Math.floor(limit.maxBytes / MB)}MB까지 올릴 수 있습니다`,
+    };
+  }
+  return null;
+}
+
 /**
  * 미디어 업로드 자리 발급 — `POST /v1/uploads`.
  *
@@ -9,6 +86,15 @@ import { z } from "zod";
  */
 export const uploadRequestSchema = z.object({
   filename: z.string().min(1).max(255),
+  purpose: uploadPurposeSchema
+    .default("description")
+    .describe("업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다"),
+  size: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("파일 바이트 크기. 주면 용도별 상한을 발급 전에 검사한다"),
 });
 
 export type UploadRequest = z.infer<typeof uploadRequestSchema>;

package/src/schemas/webhook-event.ts

@@ -44,6 +44,46 @@ export const claimWebhookEventDataSchema = z.object({
   orderItemId: z.string().describe("클레임 대상 주문 상품 ID"),
   claimType: claimTypeSchema.describe("클레임 유형"),
   status: claimStatusSchema.describe("이벤트 발생 시점의 클레임 상태"),
+  quantity: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("클레임 대상 수량. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+  refundAmount: z
+    .number()
+    .int()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "환불액 (원). 배송비 환불을 포함하고 배송비 차감·추가 차감을 뺀 실제 금액이다. " +
+        "환불이 확정되지 않은 접수 이벤트는 예상 환불액이고, 교환처럼 환불이 없으면 null이다",
+    ),
+  deliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("환불액에 포함된 배송비 (원). 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+  deliveryFeeChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 배송비 (원) — 반품·교환 배송비와 조건부 무료배송 미달 차감의 합. " +
+        "셀러가 승인에 넣은 추가 차감은 `deductAmount`로 따로 온다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
+  deductAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 추가 차감 (원) — 셀러가 클레임 승인에 넣은 금액이다(상품 훼손 등). " +
+        "배송비 차감과 별개이므로 `deliveryFeeChargeAmount`와 더해서 뺀다. 접수 이벤트와 이 필드가 없는 이전 이벤트는 0이다",
+    ),
   testPayment: z
     .boolean()
     .optional()