@sayren/store-sdk 0.5.0 → 0.6.0

package/dist/index.d.mts

@@ -976,11 +976,14 @@ export declare const claimSchema: z.ZodObject<{
   }, z.core.$strip>>;
   requestedAt: z.ZodString;
   completedAt: z.ZodNullable<z.ZodString>;
+  holdExpiresAt: z.ZodNullable<z.ZodString>;
+  holdUsed: z.ZodBoolean;
 }, z.core.$strip>;
 export type Claim = z.infer<typeof claimSchema>;
 export interface ClaimListParams extends PageParams {
   type?: ClaimType;
-  status?: ClaimStatus;
+  /** 여러 상태를 한 번에 거를 수 있다(처리 대기 목록 등) */
+  status?: ClaimStatus | ClaimStatus[];
   orderItemId?: string;
   requestedFrom?: string;
   requestedTo?: string;
@@ -994,17 +997,7 @@ export declare const claimListQuerySchema: z.ZodObject<{
     EXCHANGE: "EXCHANGE";
     CANCEL: "CANCEL";
   }>>;
-  status: z.ZodOptional<z.ZodEnum<{
-    REQUESTED: "REQUESTED";
-    HELD: "HELD";
-    COLLECTING: "COLLECTING";
-    COLLECTED: "COLLECTED";
-    REDELIVERING: "REDELIVERING";
-    APPROVED: "APPROVED";
-    REJECTED: "REJECTED";
-    COMPLETED: "COMPLETED";
-    WITHDRAWN: "WITHDRAWN";
-  }>>;
+  status: z.ZodOptional<z.ZodString>;
   orderItemId: z.ZodOptional<z.ZodString>;
   requestedFrom: z.ZodOptional<z.ZodString>;
   requestedTo: z.ZodOptional<z.ZodString>;
@@ -1061,6 +1054,8 @@ export declare const claimDetailSchema: z.ZodObject<{
   }, z.core.$strip>>;
   requestedAt: z.ZodString;
   completedAt: z.ZodNullable<z.ZodString>;
+  holdExpiresAt: z.ZodNullable<z.ZodString>;
+  holdUsed: z.ZodBoolean;
   histories: z.ZodOptional<z.ZodArray<z.ZodObject<{
     status: z.ZodEnum<{
       REQUESTED: "REQUESTED";
@@ -1245,7 +1240,7 @@ export declare const withdrawCustomerRequestSchema: z.ZodObject<{
   memo: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 export declare const customerWithdrawalBlockedDetailsSchema: z.ZodObject<{
   inProgressOrderItems: z.ZodNumber;
   openClaims: z.ZodNumber;
@@ -3542,7 +3537,7 @@ export declare function isReservedStoreCode(code: string): boolean;
 export declare const storeCodeSchema: z.ZodString;
 /** `https://shop.example.com`처럼 경로·쿼리 없는 http(s) 오리진인가 */
 export declare function isWebOrigin(value: string): boolean;
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
 export declare const analyticsOriginSchema: z.ZodString;
 /** 허용 오리진 상한 */
 export declare const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
@@ -4589,6 +4584,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
         } | null;
         requestedAt: string;
         completedAt: string | null;
+        holdExpiresAt: string | null;
+        holdUsed: boolean;
       }[];
     }>;
     get: (claimId: string) => Promise<{
@@ -4615,6 +4612,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       } | null;
       requestedAt: string;
       completedAt: string | null;
+      holdExpiresAt: string | null;
+      holdUsed: boolean;
       histories?: {
         status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
         actor: "BUYER" | "SELLER" | "SYSTEM";
@@ -4639,6 +4638,34 @@ export declare function createStoreClient(options: StoreClientOptions): {
       holdExpiresAt: string;
     }>;
     releaseHold: (claimId: string) => Promise<void>;
+    /** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+    completeExchange: (claimId: string) => Promise<{
+      claimId: string;
+      type: "RETURN" | "EXCHANGE" | "CANCEL";
+      status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
+      orderId: string;
+      orderItemId: string;
+      productName: string;
+      quantity: number;
+      reason: "CHANGE_OF_MIND" | "WRONG_ORDER" | "DEFECTIVE" | "WRONG_DELIVERY" | "DIFFERENT_FROM_PAGE" | "DELAY";
+      reasonDetail: string | null;
+      responsibility: "BUYER" | "SELLER";
+      claimDeliveryFee: number;
+      expectedRefundAmount: number | null;
+      exchangeOption: {
+        optionId: string;
+        optionName: string;
+      } | null;
+      collect: {
+        method: "SELLER_PICKUP" | "BUYER_SEND";
+        carrierCode: string | null;
+        trackingNumber: string | null;
+      } | null;
+      requestedAt: string;
+      completedAt: string | null;
+      holdExpiresAt: string | null;
+      holdUsed: boolean;
+    }>;
   };
   inquiries: {
     list: (params?: PageParams & {
@@ -4993,7 +5020,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     }>;
   };
   /**
-   * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+   * 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
    * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
    * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
    */
@@ -6124,7 +6151,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
     }>;
     /**
      * `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-     * 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+     * 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
      */
     update: (body: UpdateStoreRequest) => Promise<{
       storeId: string;

package/dist/index.mjs

@@ -150,7 +150,7 @@ function createHttp(options) {
 /**
 * 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
 *
-* 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+* 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
 * 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
 */
 const reportDate$1 = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "날짜 형식은 YYYY-MM-DD 입니다");
@@ -654,12 +654,16 @@ const claimSchema = z.object({
 		trackingNumber: z.string().nullable()
 	}).nullable(),
 	requestedAt: z.string(),
-	completedAt: z.string().nullable()
+	completedAt: z.string().nullable(),
+	/** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
+	holdExpiresAt: z.string().nullable(),
+	/** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
+	holdUsed: z.boolean()
 });
 /** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
 const claimListQuerySchema = z.object({
 	type: claimTypeSchema.optional().describe("클레임 유형 필터"),
-	status: claimStatusSchema.optional().describe("클레임 상태 필터"),
+	status: z.string().optional().describe("클레임 상태 필터. 쉼표로 여러 개를 줄 수 있다 (예: `REQUESTED,HELD,COLLECTED`)"),
 	orderItemId: z.string().optional().describe("주문상품 id 필터"),
 	requestedFrom: z.string().optional().describe("요청 시각 조회 시작 (ISO 8601, 포함)"),
 	requestedTo: z.string().optional().describe("요청 시각 조회 끝 (ISO 8601, 포함)"),
@@ -798,7 +802,7 @@ const withdrawCustomerRequestSchema = z.object({
 	]).describe("처리 사유 — 구매자 요청·장기 미이용·부정 이용·기타. 감사 로그에 남는다"),
 	memo: z.string().max(200).optional().describe("사유 보충(선택)")
 });
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 const customerWithdrawalBlockedDetailsSchema = z.object({
 	inProgressOrderItems: z.number().int(),
 	openClaims: z.number().int(),
@@ -816,7 +820,7 @@ const loginProviderSchema = z.enum([
 const loginProviderStatusSchema = z.object({
 	provider: loginProviderSchema,
 	connected: z.boolean(),
-	/** 스토어프런트에서 사용 중인지. 연결 안 됐으면 false */
+	/** 스토어프론트에서 사용 중인지. 연결 안 됐으면 false */
 	enabled: z.boolean(),
 	clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
 	secretPrefix: z.string().nullable(),
@@ -1600,10 +1604,10 @@ const productSummarySchema = z.object({
 	productId: z.string(),
 	name: z.string(),
 	status: productStatusSchema,
-	salePrice: z.number().int(),
-	discountedPrice: z.number().int().nullable(),
+	salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
+	discountedPrice: z.number().int().nullable().describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
 	/** usable variant 재고 합계 (서버 계산) */
-	stockQuantity: z.number().int(),
+	stockQuantity: z.number().int().describe("판매 가능한 옵션 재고의 합계. 서버가 계산한다"),
 	categoryId: z.string().nullable(),
 	thumbnailUrl: z.url().optional(),
 	/** optionGroups.length > 0 */
@@ -1740,8 +1744,8 @@ const variantStockSchema = z.object({
 const productCreateRequestSchema = z.object({
 	name: z.string().min(1).max(100),
 	categoryId: z.string().min(1, "카테고리를 선택해주세요"),
-	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
-	originalPrice: z.number().int().optional(),
+	salePrice: z.number().int().min(10).multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)").describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+	originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
 	description: z.string().optional(),
 	/**
 	* 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -1753,11 +1757,11 @@ const productCreateRequestSchema = z.object({
 		attributeId: z.string(),
 		value: z.string()
 	})).optional(),
-	deliveryType: deliveryTypeSchema.default("PAID"),
-	deliveryFee: z.number().int().default(0),
-	conditionalFreeAmount: z.number().int().optional(),
-	returnFee: z.number().int().default(0),
-	exchangeFee: z.number().int().default(0),
+	deliveryType: deliveryTypeSchema.default("PAID").describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
+	deliveryFee: z.number().int().default(0).describe("배송비. 원 단위"),
+	conditionalFreeAmount: z.number().int().optional().describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
+	returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위"),
+	exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위"),
 	shippingAddressId: z.string().optional(),
 	returnAddressId: z.string().optional()
 }).extend(optionModelRequestSchema.shape);
@@ -1873,8 +1877,8 @@ function isWebOrigin(value) {
 		return false;
 	}
 }
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
-const analyticsOriginSchema = z.string().trim().max(255).refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요").describe("스토어프런트 오리진. 예: `https://shop.example.com`");
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+const analyticsOriginSchema = z.string().trim().max(255).refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요").describe("스토어프론트 오리진. 예: `https://shop.example.com`");
 /** 허용 오리진 상한 */
 const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
@@ -1883,8 +1887,8 @@ const updateStoreRequestSchema = z.object({
 	logoUrl: z.url().optional(),
 	customerCenterPhone: z.string().optional(),
 	businessHours: z.string().max(100).optional(),
-	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
-	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프런트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
+	analyticsAllowedOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프론트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. 넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다"),
+	storefrontOrigins: z.array(analyticsOriginSchema).max(20).optional().describe("스토어프론트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. `analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
 	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다")
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 const storeSchema = z.object({
@@ -1900,8 +1904,8 @@ const storeSchema = z.object({
 	logoUrl: z.url().nullable(),
 	businessNumber: z.string().nullable(),
 	customerCenterPhone: z.string().nullable(),
-	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
-	storefrontOrigins: z.array(z.string()).describe("스토어프런트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
+	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+	storefrontOrigins: z.array(z.string()).describe("스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
 	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
 	memberCount: z.number().int(),
 	createdAt: z.string()
@@ -2188,7 +2192,10 @@ function createStoreClient(options) {
 		},
 		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
 		claims: {
-			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params }),
+			list: (params) => storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: {
+				...params,
+				status: Array.isArray(params?.status) ? params.status.join(",") : params?.status
+			} }),
 			get: (claimId) => storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
 			approve: (claimId, deductAmount, idempotencyKey) => storeHttp.request("POST", path`/claims/${claimId}/approve`, approveClaimResultSchema, {
 				body: deductAmount !== void 0 ? { deductAmount } : {},
@@ -2202,7 +2209,9 @@ function createStoreClient(options) {
 				trackingNumber
 			} }),
 			hold: (claimId, reason) => storeHttp.request("POST", path`/claims/${claimId}/hold`, claimHoldResultSchema, { body: { reason } }),
-			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`)
+			releaseHold: (claimId) => storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
+			/** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+			completeExchange: (claimId) => storeHttp.request("POST", path`/claims/${claimId}/complete-exchange`, claimSchema)
 		},
 		inquiries: {
 			list: (params) => storeHttp.request("GET", "/inquiries", pageSchema(inquirySchema), { query: params }),
@@ -2258,7 +2267,7 @@ function createStoreClient(options) {
 		*/
 get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, { query: salesReportQuerySchema.parse(params) }) },
 		/**
-		* 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+		* 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
 		* 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
 		* 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
 		*/
@@ -2414,7 +2423,7 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			get: () => storeHttp.request("GET", "/store", storeSchema),
 			/**
 			* `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-			* 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+			* 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
 			*/
 			update: (body) => storeHttp.request("PATCH", "/store", storeSchema, { body: updateStoreRequestSchema.parse(body) }),
 			listMembers: () => storeHttp.request("GET", "/store/members", z.array(storeMemberSchema)),

package/package.json

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

package/src/client.ts

@@ -533,7 +533,12 @@ export function createStoreClient(options: StoreClientOptions) {
 
     claims: {
       list: (params?: ClaimListParams) =>
-        storeHttp.request("GET", "/claims", pageSchema(claimSchema), { query: params as Query }),
+        storeHttp.request("GET", "/claims", pageSchema(claimSchema), {
+          query: {
+            ...params,
+            status: Array.isArray(params?.status) ? params.status.join(",") : params?.status,
+          } as Query,
+        }),
       get: (claimId: string) =>
         storeHttp.request("GET", path`/claims/${claimId}`, claimDetailSchema),
       approve: (claimId: string, deductAmount?: number, idempotencyKey?: string) =>
@@ -561,6 +566,9 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       releaseHold: (claimId: string) =>
         storeHttp.requestVoid("DELETE", path`/claims/${claimId}/hold`),
+      /** 교환 완료 — 재배송 중인 교환을 셀러가 명시적으로 끝낸다 */
+      completeExchange: (claimId: string) =>
+        storeHttp.request("POST", path`/claims/${claimId}/complete-exchange`, claimSchema),
     },
 
     inquiries: {
@@ -691,7 +699,7 @@ export function createStoreClient(options: StoreClientOptions) {
     },
 
     /**
-     * 방문 분석 — 스코프 `analytics:r`. 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
+     * 방문 분석 — 스코프 `analytics:r`. 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 Asia/Seoul 날짜별로
      * 집계한 값이다. 집계는 주기적으로 갱신되고 응답 `lastComputedAt`이 마지막 집계 시각이다. 봇 세션은 빠진다.
      * 기간은 양끝 포함 최대 92일이고, 테스트 결제 구매는 `includeTest: "true"`일 때만 포함한다.
      */
@@ -944,7 +952,7 @@ export function createStoreClient(options: StoreClientOptions) {
       get: () => storeHttp.request("GET", "/store", storeSchema),
       /**
        * `PATCH /v1/store` — 스코프 `store:rw`. 바꿀 필드만 보낸다. `analyticsAllowedOrigins`는 방문 분석 수집을 받을
-       * 스토어프런트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
+       * 스토어프론트 오리진 목록이다(빈 배열이면 모든 오리진 허용).
        */
       update: (body: UpdateStoreRequest) =>
         storeHttp.request("PATCH", "/store", storeSchema, {

package/src/schemas/analytics.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 /**
  * 방문 분석 조회 (관리 API `/v1/analytics/*`, 스코프 `analytics:r`).
  *
- * 스토어프런트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
+ * 스토어프론트가 `@sayren/storefront-sdk`로 수집한 이벤트를 서버가 날짜(Asia/Seoul)별로 집계한 값이다. 집계는 주기적으로
  * 갱신되므로 오늘 값은 `lastComputedAt` 시점까지 반영돼 있다. 봇·자동화 브라우저의 세션은 모든 집계에서 빠진다.
  */
 

package/src/schemas/claim.ts

@@ -53,13 +53,18 @@ export const claimSchema = z.object({
     .nullable(),
   requestedAt: z.string(),
   completedAt: z.string().nullable(),
+  /** 보류 중이면 자동 해제 시각(ISO 8601), 아니면 null */
+  holdExpiresAt: z.string().nullable(),
+  /** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
+  holdUsed: z.boolean(),
 });
 
 export type Claim = z.infer<typeof claimSchema>;
 
 export interface ClaimListParams extends PageParams {
   type?: ClaimType;
-  status?: ClaimStatus;
+  /** 여러 상태를 한 번에 거를 수 있다(처리 대기 목록 등) */
+  status?: ClaimStatus | ClaimStatus[];
   orderItemId?: string;
   requestedFrom?: string;
   requestedTo?: string;
@@ -68,7 +73,10 @@ export interface ClaimListParams extends PageParams {
 /** `GET /v1/claims` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
 export const claimListQuerySchema = z.object({
   type: claimTypeSchema.optional().describe("클레임 유형 필터"),
-  status: claimStatusSchema.optional().describe("클레임 상태 필터"),
+  status: z
+    .string()
+    .optional()
+    .describe("클레임 상태 필터. 쉼표로 여러 개를 줄 수 있다 (예: `REQUESTED,HELD,COLLECTED`)"),
   orderItemId: z.string().optional().describe("주문상품 id 필터"),
   requestedFrom: z.string().optional().describe("요청 시각 조회 시작 (ISO 8601, 포함)"),
   requestedTo: z.string().optional().describe("요청 시각 조회 끝 (ISO 8601, 포함)"),

package/src/schemas/customer.ts

@@ -115,7 +115,7 @@ export const withdrawCustomerRequestSchema = z.object({
 });
 export type WithdrawCustomerRequest = z.infer<typeof withdrawCustomerRequestSchema>;
 
-/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프런트 탈퇴와 같다) */
+/** `WITHDRAWAL_BLOCKED`의 `error.details` — 탈퇴를 막는 항목 수(스토어프론트 탈퇴와 같다) */
 export const customerWithdrawalBlockedDetailsSchema = z.object({
   inProgressOrderItems: z.number().int(),
   openClaims: z.number().int(),

package/src/schemas/login.ts

@@ -8,7 +8,7 @@ export type LoginProvider = z.infer<typeof loginProviderSchema>;
 export const loginProviderStatusSchema = z.object({
   provider: loginProviderSchema,
   connected: z.boolean(),
-  /** 스토어프런트에서 사용 중인지. 연결 안 됐으면 false */
+  /** 스토어프론트에서 사용 중인지. 연결 안 됐으면 false */
   enabled: z.boolean(),
   clientIdPrefix: z.string().nullable().describe("클라이언트 ID(카카오 REST API 키) 앞 4자리"),
   secretPrefix: z.string().nullable(),

package/src/schemas/product.ts

@@ -13,10 +13,14 @@ export const productSummarySchema = z.object({
   productId: z.string(),
   name: z.string(),
   status: productStatusSchema,
-  salePrice: z.number().int(),
-  discountedPrice: z.number().int().nullable(),
+  salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
+  discountedPrice: z
+    .number()
+    .int()
+    .nullable()
+    .describe("즉시 할인 적용가. 원 단위. 할인이 없으면 null"),
   /** usable variant 재고 합계 (서버 계산) */
-  stockQuantity: z.number().int(),
+  stockQuantity: z.number().int().describe("판매 가능한 옵션 재고의 합계. 서버가 계산한다"),
   categoryId: z.string().nullable(),
   thumbnailUrl: z.url().optional(),
   /** optionGroups.length > 0 */
@@ -199,8 +203,9 @@ export const productCreateRequestSchema = z
       .number()
       .int()
       .min(10)
-      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)"),
-    originalPrice: z.number().int().optional(),
+      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
+      .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+    originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
     description: z.string().optional(),
     /**
      * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -209,11 +214,17 @@ export const productCreateRequestSchema = z
     descriptionJson: z.string().nullable().optional(),
     images: z.array(z.url()).min(1).max(10).optional(),
     attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
-    deliveryType: deliveryTypeSchema.default("PAID"),
-    deliveryFee: z.number().int().default(0),
-    conditionalFreeAmount: z.number().int().optional(),
-    returnFee: z.number().int().default(0),
-    exchangeFee: z.number().int().default(0),
+    deliveryType: deliveryTypeSchema
+      .default("PAID")
+      .describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
+    deliveryFee: z.number().int().default(0).describe("배송비. 원 단위"),
+    conditionalFreeAmount: z
+      .number()
+      .int()
+      .optional()
+      .describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
+    returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위"),
+    exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위"),
     shippingAddressId: z.string().optional(),
     returnAddressId: z.string().optional(),
   })

package/src/schemas/store.ts

@@ -91,13 +91,13 @@ export function isWebOrigin(value: string): boolean {
   }
 }
 
-/** 방문 분석을 보낼 수 있는 스토어프런트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
+/** 방문 분석을 보낼 수 있는 스토어프론트 오리진 — 스킴·호스트(·포트)만. 서버가 소문자·끝 슬래시 제거로 정규화한다 */
 export const analyticsOriginSchema = z
   .string()
   .trim()
   .max(255)
   .refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요")
-  .describe("스토어프런트 오리진. 예: `https://shop.example.com`");
+  .describe("스토어프론트 오리진. 예: `https://shop.example.com`");
 
 /** 허용 오리진 상한 */
 export const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
@@ -114,7 +114,7 @@ export const updateStoreRequestSchema = z
       .max(MAX_ANALYTICS_ALLOWED_ORIGINS)
       .optional()
       .describe(
-        "@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프런트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. " +
+        "@deprecated `storefrontOrigins`를 쓴다(같은 목록). 방문 분석 수집을 받을 스토어프론트 오리진(최대 20개). 비우면 모든 오리진에서 받는다. " +
           "넣으면 목록에 없는 오리진의 수집 요청은 403 `ORIGIN_NOT_ALLOWED`이고, 페이지 URL이 목록 밖인 이벤트는 버린다",
       ),
     storefrontOrigins: z
@@ -122,7 +122,7 @@ export const updateStoreRequestSchema = z
       .max(MAX_ANALYTICS_ALLOWED_ORIGINS)
       .optional()
       .describe(
-        "스토어프런트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. " +
+        "스토어프론트 도메인(최대 20개) — 소셜 로그인 뒤 돌아갈 주소와 방문 분석 수집을 함께 제한한다. " +
           "`analyticsAllowedOrigins`와 같은 목록이다(둘 다 주면 이 값이 이긴다)",
       ),
     guestCheckoutEnabled: z
@@ -149,11 +149,11 @@ export const storeSchema = z.object({
   customerCenterPhone: z.string().nullable(),
   analyticsAllowedOrigins: z
     .array(z.string())
-    .describe("방문 분석 수집을 받는 스토어프런트 오리진. 비어 있으면 모든 오리진에서 받는다"),
+    .describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
   storefrontOrigins: z
     .array(z.string())
     .describe(
-      "스토어프런트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
+      "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
   memberCount: z.number().int(),