@sayren/store-sdk 0.8.0 → 0.9.0

package/dist/index.d.mts

@@ -1050,6 +1050,7 @@ export declare const changeTypeSchema: z.ZodEnum<{
   "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
   "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
   "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+  "CLAIM.COMPLETED": "CLAIM.COMPLETED";
 }>;
 export type ChangeType = z.infer<typeof changeTypeSchema>;
 //#endregion
@@ -2011,6 +2012,7 @@ export declare const orderItemSchema: z.ZodObject<{
     "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
     "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
     "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+    "CLAIM.COMPLETED": "CLAIM.COMPLETED";
   }>;
   testPayment: z.ZodBoolean;
 }, z.core.$strip>;
@@ -2095,6 +2097,7 @@ export declare const orderSchema: z.ZodObject<{
       "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
       "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
       "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+      "CLAIM.COMPLETED": "CLAIM.COMPLETED";
     }>;
     testPayment: z.ZodBoolean;
   }, z.core.$strip>>;
@@ -2177,6 +2180,7 @@ export declare const orderItemPageSchema: z.ZodObject<{
       "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
       "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
       "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+      "CLAIM.COMPLETED": "CLAIM.COMPLETED";
     }>;
     testPayment: z.ZodBoolean;
   }, z.core.$strip>>;
@@ -2227,6 +2231,7 @@ export declare const orderItemListQuerySchema: z.ZodObject<{
     "CLAIM.CANCEL_REQUESTED": "CLAIM.CANCEL_REQUESTED";
     "CLAIM.RETURN_REQUESTED": "CLAIM.RETURN_REQUESTED";
     "CLAIM.EXCHANGE_REQUESTED": "CLAIM.EXCHANGE_REQUESTED";
+    "CLAIM.COMPLETED": "CLAIM.COMPLETED";
   }>>;
   testPayment: z.ZodOptional<z.ZodEnum<{
     true: "true";
@@ -3458,6 +3463,33 @@ export declare const productSchema: z.ZodObject<{
   createdAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Product = z.infer<typeof productSchema>;
+/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
+export declare const MAX_PRODUCT_IMAGES = 10;
+/**
+ * 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
+ *
+ * https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
+ * **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
+ * 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
+ *
+ * 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
+ * 만들면 상품 조회 자체가 막힌다.
+ */
+export declare const productImageUrlSchema: z.ZodURL;
+export interface ProductImageRejection {
+  code: "INVALID_IMAGE_URL" | "UNSUPPORTED_FILE_TYPE";
+  message: string;
+}
+/**
+ * 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
+ *
+ * - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
+ *   상세 화면에 박히는 주입 경로가 된다.
+ * - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
+ * - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
+ *   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+ */
+export declare function productImageRejection(url: string): ProductImageRejection | null;
 /** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
 export declare const MAX_OPTION_GROUPS = 3;
 /** 축 하나가 가질 수 있는 값의 최대 개수 */
@@ -3655,15 +3687,6 @@ export declare const productListQuerySchema: z.ZodObject<{
     "updatedAt.desc": "updatedAt.desc";
   }>>;
 }, z.core.$strip>;
-/** `POST /v1/product-images` 응답 — 업로드된 이미지의 CDN 주소 */
-export declare const productImageUploadResultSchema: z.ZodObject<{
-  images: z.ZodArray<z.ZodObject<{
-    url: z.ZodURL;
-    width: z.ZodNumber;
-    height: z.ZodNumber;
-  }, z.core.$strip>>;
-}, z.core.$strip>;
-export type ProductImageUploadResult = z.infer<typeof productImageUploadResultSchema>;
 export declare const discountSchema: z.ZodObject<{
   productId: z.ZodString;
   discountType: z.ZodEnum<{
@@ -3706,6 +3729,8 @@ export declare function isWebOrigin(value: string): boolean;
 export declare const analyticsOriginSchema: z.ZodString;
 /** 허용 오리진 상한 */
 export declare const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
+/** 자동 배송완료·자동 구매확정 대기일 상한 */
+export declare const MAX_AUTO_TRANSITION_DAYS = 30;
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
 export declare const updateStoreRequestSchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
@@ -3715,6 +3740,8 @@ export declare const updateStoreRequestSchema: z.ZodObject<{
   analyticsAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
   storefrontOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
   guestCheckoutEnabled: z.ZodOptional<z.ZodBoolean>;
+  autoDeliverDays: z.ZodOptional<z.ZodNumber>;
+  autoConfirmDays: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type UpdateStoreRequest = z.infer<typeof updateStoreRequestSchema>;
 export declare const storeSchema: z.ZodObject<{
@@ -3733,6 +3760,8 @@ export declare const storeSchema: z.ZodObject<{
   analyticsAllowedOrigins: z.ZodArray<z.ZodString>;
   storefrontOrigins: z.ZodArray<z.ZodString>;
   guestCheckoutEnabled: z.ZodBoolean;
+  autoDeliverDays: z.ZodNumber;
+  autoConfirmDays: z.ZodNumber;
   memberCount: z.ZodNumber;
   createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -3829,6 +3858,42 @@ export declare const sellerAddressRequestSchema: z.ZodObject<{
 export type SellerAddressRequest = z.infer<typeof sellerAddressRequestSchema>;
 //#endregion
 //#region src/schemas/upload.d.ts
+/**
+ * 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
+ *
+ * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
+ * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+ */
+export declare const uploadPurposeSchema: z.ZodEnum<{
+  "product-image": "product-image";
+  description: "description";
+}>;
+export type UploadPurpose = z.infer<typeof uploadPurposeSchema>;
+export interface UploadPurposeLimit {
+  /** 소문자 확장자 목록 */
+  extensions: readonly string[];
+  maxBytes: number;
+}
+/**
+ * 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
+ *
+ * 크기는 **요청이 스스로 신고한 값**으로만 검사한다. 바이트는 api를 거치지 않고 CDN으로
+ * 직접 PUT되므로 이 검사는 셀러가 올리기 전에 알게 하는 장치이고, 실제 상한은 CDN이 강제한다.
+ */
+export declare const UPLOAD_PURPOSE_LIMITS: Record<UploadPurpose, UploadPurposeLimit>;
+/** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
+export declare function uploadExtensionOf(filename: string): string;
+export interface UploadRejection {
+  /** 400 형식 불일치 / 413 크기 초과 */
+  status: 400 | 413;
+  code: "UNSUPPORTED_FILE_TYPE" | "FILE_TOO_LARGE";
+  message: string;
+}
+/**
+ * 용도 제한 위반 여부. 통과하면 `null`.
+ * 서버가 던지는 오류와 콘솔이 먼저 띄우는 안내가 갈리지 않도록 한 함수로 판정한다.
+ */
+export declare function uploadRejection(purpose: UploadPurpose, filename: string, size?: number): UploadRejection | null;
 /**
  * 미디어 업로드 자리 발급 — `POST /v1/uploads`.
  *
@@ -3838,6 +3903,11 @@ export type SellerAddressRequest = z.infer<typeof sellerAddressRequestSchema>;
  */
 export declare const uploadRequestSchema: z.ZodObject<{
   filename: z.ZodString;
+  purpose: z.ZodDefault<z.ZodEnum<{
+    "product-image": "product-image";
+    description: "description";
+  }>>;
+  size: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type UploadRequest = z.infer<typeof uploadRequestSchema>;
 export declare const uploadTicketSchema: z.ZodObject<{
@@ -4123,6 +4193,16 @@ export declare function createStoreClient(options: StoreClientOptions): {
       url: string;
       uploadUrl: string;
     }>;
+    /**
+     * 자리 발급 + 바이트 PUT을 한 번에 — 끝나면 `url`이 공개 주소다.
+     *
+     * 용도 제한(확장자·크기)은 서버가 판정하지만, 같은 규칙으로 여기서 먼저 걸러
+     * 큰 파일을 CDN까지 보내고 나서 거절되는 왕복을 없앤다.
+     */
+    upload: (file: Blob, options?: {
+      purpose?: UploadPurpose;
+      filename?: string;
+    }) => Promise<UploadTicket>;
   };
   products: {
     list: (params?: ProductListParams) => Promise<{
@@ -4609,7 +4689,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         sellerMemo: string | null;
         orderedAt: string;
         lastChangedAt: string;
-        lastChangedType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED";
+        lastChangedType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED" | "CLAIM.COMPLETED";
         testPayment: boolean;
       }[];
     }>;
@@ -4643,7 +4723,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         sellerMemo: string | null;
         orderedAt: string;
         lastChangedAt: string;
-        lastChangedType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED";
+        lastChangedType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED" | "CLAIM.COMPLETED";
         testPayment: boolean;
       }[];
     }>;
@@ -4696,6 +4776,46 @@ export declare function createStoreClient(options: StoreClientOptions): {
       }[];
     }>;
     updateTracking: (orderItemId: string, carrierCode: string, trackingNumber: string) => Promise<void>;
+    /**
+     * 배송완료 처리 — `DISPATCHED`·`DELIVERING`만 넘어간다. 응답의 `autoDecisionDate`가 자동 구매확정 예정일이다
+     * (스토어 설정 `autoConfirmDays`가 0이면 null).
+     */
+    markDelivered: (orderItemId: string, idempotencyKey?: string) => Promise<{
+      orderItemId: string;
+      orderId: string;
+      status: "PAID" | "PAYMENT_WAITING" | "CONFIRMED" | "DISPATCHED" | "DELIVERING" | "DELIVERED" | "PURCHASE_DECIDED" | "CANCELED";
+      claimStatus: "CANCEL_REQUESTED" | "RETURN_REQUESTED" | "EXCHANGE_REQUESTED" | null;
+      productId: string;
+      productName: string;
+      optionId: string | null;
+      optionName: string | null;
+      sellerCode: string | null;
+      quantity: number;
+      unitPrice: number;
+      discountAmount: number;
+      totalPrice: number;
+      hold: {
+        reason: string;
+        expectedDispatchDate: string;
+      } | null;
+      autoDecisionDate: string | null;
+      sellerMemo: string | null;
+      orderedAt: string;
+      lastChangedAt: string;
+      lastChangedType: "ORDER.PAID" | "ORDER.CONFIRMED" | "ORDER.DISPATCHED" | "ORDER.DELIVERED" | "ORDER.PURCHASE_DECIDED" | "ORDER.ADDRESS_CHANGE_REQUESTED" | "CLAIM.CANCEL_REQUESTED" | "CLAIM.RETURN_REQUESTED" | "CLAIM.EXCHANGE_REQUESTED" | "CLAIM.COMPLETED";
+      testPayment: boolean;
+    }>;
+    /** 배송완료 일괄 처리 — 항목별 부분 성공이다 */
+    markDeliveredBulk: (orderItemIds: string[], idempotencyKey?: string) => Promise<{
+      succeeded: string[];
+      failed: {
+        code: string;
+        message: string;
+        id?: string | undefined;
+        productId?: string | undefined;
+        orderItemId?: string | undefined;
+      }[];
+    }>;
     getDelivery: (orderItemId: string) => Promise<{
       orderItemId: string;
       deliveryMethod: "COURIER" | "DIRECT" | "QUICK" | "NOTHING";
@@ -6418,6 +6538,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       analyticsAllowedOrigins: string[];
       storefrontOrigins: string[];
       guestCheckoutEnabled: boolean;
+      autoDeliverDays: number;
+      autoConfirmDays: number;
       memberCount: number;
       createdAt: string;
     }>;
@@ -6437,6 +6559,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       analyticsAllowedOrigins: string[];
       storefrontOrigins: string[];
       guestCheckoutEnabled: boolean;
+      autoDeliverDays: number;
+      autoConfirmDays: number;
       memberCount: number;
       createdAt: string;
     }>;

package/dist/index.mjs

@@ -693,6 +693,7 @@ const changeTypeSchema = z.enum([
 	"CLAIM.CANCEL_REQUESTED",
 	"CLAIM.RETURN_REQUESTED",
 	"CLAIM.EXCHANGE_REQUESTED",
+	"CLAIM.COMPLETED",
 	"ORDER.ADDRESS_CHANGE_REQUESTED"
 ]);
 //#endregion
@@ -1692,6 +1693,92 @@ const purchaseDecisionExtendResultSchema = z.object({
 */
 const addressChangeRequestListSchema = z.array(z.record(z.string(), z.unknown())).describe("배송지 변경 요청 목록 (현재 항상 빈 배열)");
 //#endregion
+//#region src/schemas/upload.ts
+/**
+* 업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다.
+*
+* - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
+* - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+*/
+const uploadPurposeSchema = z.enum(["product-image", "description"]);
+const MB = 1048576;
+/**
+* 용도별 업로드 제한 — 서버(`POST /v1/uploads`)와 클라이언트가 공유하는 단일 원천이다.
+*
+* 크기는 **요청이 스스로 신고한 값**으로만 검사한다. 바이트는 api를 거치지 않고 CDN으로
+* 직접 PUT되므로 이 검사는 셀러가 올리기 전에 알게 하는 장치이고, 실제 상한은 CDN이 강제한다.
+*/
+const UPLOAD_PURPOSE_LIMITS = {
+	"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
+	}
+};
+/** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
+function uploadExtensionOf(filename) {
+	const dot = filename.lastIndexOf(".");
+	if (dot < 0 || dot === filename.length - 1) return "";
+	return filename.slice(dot + 1).toLowerCase();
+}
+/**
+* 용도 제한 위반 여부. 통과하면 `null`.
+* 서버가 던지는 오류와 콘솔이 먼저 띄우는 안내가 갈리지 않도록 한 함수로 판정한다.
+*/
+function uploadRejection(purpose, filename, size) {
+	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 !== void 0 && size > limit.maxBytes) return {
+		status: 413,
+		code: "FILE_TOO_LARGE",
+		message: `파일이 너무 큽니다. ${Math.floor(limit.maxBytes / MB)}MB까지 올릴 수 있습니다`
+	};
+	return null;
+}
+/**
+* 미디어 업로드 자리 발급 — `POST /v1/uploads`.
+*
+* 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
+* 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
+* (확장자만 쓰이고 이름 자체는 저장되지 않는다).
+*/
+const uploadRequestSchema = z.object({
+	filename: z.string().min(1).max(255),
+	purpose: uploadPurposeSchema.default("description").describe("업로드 용도. 허용 확장자와 크기 상한이 용도별로 다르다"),
+	size: z.number().int().positive().optional().describe("파일 바이트 크기. 주면 용도별 상한을 발급 전에 검사한다")
+});
+const uploadTicketSchema = z.object({
+	/** 업로드 완료 후 공개될 주소 */
+	url: z.url(),
+	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
+	uploadUrl: z.url()
+});
+//#endregion
 //#region src/schemas/product.ts
 const productStatusSchema = z.enum([
 	"SALE",
@@ -1775,6 +1862,54 @@ const productSchema = productSummarySchema.extend({
 	returnAddressId: z.string().nullable().optional(),
 	createdAt: z.string().optional()
 });
+/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
+const MAX_PRODUCT_IMAGES = 10;
+/**
+* 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
+*
+* https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
+* **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
+* 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
+*
+* 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
+* 만들면 상품 조회 자체가 막힌다.
+*/
+const productImageUrlSchema = z.url().max(2048).describe("상품 이미지 주소. https만 허용하고, 확장자가 있으면 이미지 형식이어야 한다");
+/**
+* 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
+*
+* - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
+*   상세 화면에 박히는 주입 경로가 된다.
+* - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
+* - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
+*   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+*/
+function productImageRejection(url) {
+	if (url.length > 2048) return {
+		code: "INVALID_IMAGE_URL",
+		message: "이미지 주소가 너무 깁니다"
+	};
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return {
+			code: "INVALID_IMAGE_URL",
+			message: "이미지 주소 형식이 아닙니다"
+		};
+	}
+	if (parsed.protocol !== "https:") return {
+		code: "INVALID_IMAGE_URL",
+		message: "이미지 주소는 https로 시작해야 합니다"
+	};
+	const extension = uploadExtensionOf(parsed.pathname);
+	const allowed = UPLOAD_PURPOSE_LIMITS["product-image"].extensions;
+	if (extension && !allowed.includes(extension)) return {
+		code: "UNSUPPORTED_FILE_TYPE",
+		message: `상품 이미지는 ${allowed.join(", ")}만 쓸 수 있습니다`
+	};
+	return null;
+}
 /** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
 const MAX_OPTION_GROUPS = 3;
 /** 축 하나가 가질 수 있는 값의 최대 개수 */
@@ -1856,7 +1991,7 @@ const productCreateRequestSchema = z.object({
 	* 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
 	*/
 	descriptionJson: z.string().nullable().optional(),
-	images: z.array(z.url()).min(1).max(10).optional(),
+	images: z.array(productImageUrlSchema).min(1).max(10).optional().describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
 	attributes: z.array(z.object({
 		attributeId: z.string(),
 		value: z.string()
@@ -1891,12 +2026,6 @@ const productListQuerySchema = z.object({
 	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
 	...pageQueryShape()
 });
-/** `POST /v1/product-images` 응답 — 업로드된 이미지의 CDN 주소 */
-const productImageUploadResultSchema = z.object({ images: z.array(z.object({
-	url: z.url(),
-	width: z.number().int(),
-	height: z.number().int()
-})) });
 const discountSchema = z.object({
 	productId: z.string(),
 	discountType: z.enum(["RATE", "AMOUNT"]),
@@ -1985,6 +2114,10 @@ function isWebOrigin(value) {
 const analyticsOriginSchema = z.string().trim().max(255).refine(isWebOrigin, "https://shop.example.com 형식(경로 없이)으로 입력해 주세요").describe("스토어프론트 오리진. 예: `https://shop.example.com`");
 /** 허용 오리진 상한 */
 const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
+/** 자동 배송완료·자동 구매확정 대기일 상한 */
+const MAX_AUTO_TRANSITION_DAYS = 30;
+const autoDeliverDaysDescription = "발송 후 자동 배송완료까지의 일수(0~30, 기본 7). 발송(`DISPATCHED`)·배송중(`DELIVERING`) 주문상품을 이 기간이 지나면 배송완료(`DELIVERED`)로 바꾼다. `0`이면 자동 배송완료를 하지 않는다";
+const autoConfirmDaysDescription = "배송완료 후 자동 구매확정까지의 일수(0~30, 기본 7). 배송완료 시점에 구매확정 예정일(`autoDecisionDate`)을 이 값으로 잡고, 그 날짜가 지나면 구매확정(`PURCHASE_DECIDED`)으로 바꾼다. 진행 중인 클레임이 있으면 건너뛴다. `0`이면 자동 구매확정을 하지 않는다";
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
 const updateStoreRequestSchema = z.object({
 	name: z.string().min(2).max(50).optional(),
@@ -1993,7 +2126,9 @@ const updateStoreRequestSchema = z.object({
 	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`와 같은 목록이다(둘 다 주면 이 값이 이긴다)"),
-	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다")
+	guestCheckoutEnabled: z.boolean().optional().describe("비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. 장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다"),
+	autoDeliverDays: z.number().int().min(0).max(30).optional().describe(autoDeliverDaysDescription),
+	autoConfirmDays: z.number().int().min(0).max(30).optional().describe(autoConfirmDaysDescription)
 }).refine((value) => Object.values(value).some((v) => v !== void 0), { message: "최소 1개 필드가 필요합니다" });
 const storeSchema = z.object({
 	storeId: z.string(),
@@ -2011,6 +2146,8 @@ const storeSchema = z.object({
 	analyticsAllowedOrigins: z.array(z.string()).describe("방문 분석 수집을 받는 스토어프론트 오리진. 비어 있으면 모든 오리진에서 받는다"),
 	storefrontOrigins: z.array(z.string()).describe("스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)"),
 	guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+	autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
+	autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
 	memberCount: z.number().int(),
 	createdAt: z.string()
 });
@@ -2068,22 +2205,6 @@ const sellerAddressRequestSchema = z.object({
 	address2: z.string().optional()
 });
 //#endregion
-//#region src/schemas/upload.ts
-/**
-* 미디어 업로드 자리 발급 — `POST /v1/uploads`.
-*
-* 파일 바이트는 api를 거치지 않는다. 응답의 `uploadUrl`로 클라이언트가 직접 PUT하고,
-* 끝나면 `url`이 공개 주소가 된다. 서버가 객체 키를 정하므로 요청은 파일명만 보낸다
-* (확장자만 쓰이고 이름 자체는 저장되지 않는다).
-*/
-const uploadRequestSchema = z.object({ filename: z.string().min(1).max(255) });
-const uploadTicketSchema = z.object({
-	/** 업로드 완료 후 공개될 주소 */
-	url: z.url(),
-	/** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
-	uploadUrl: z.url()
-});
-//#endregion
 //#region src/client.ts
 function formBody(fields) {
 	return new URLSearchParams(fields).toString();
@@ -2211,7 +2332,35 @@ function createStoreClient(options) {
 		* 미디어 업로드 — 자리를 받아(`POST /uploads`) 파일 바이트는 호출자가
 		* `uploadUrl`로 직접 PUT한다. 업로드가 끝나면 `url`이 공개 주소가 된다.
 		*/
-		uploads: { create: (body) => storeHttp.request("POST", "/uploads", uploadTicketSchema, { body: uploadRequestSchema.parse(body) }) },
+		uploads: {
+			create: (body) => storeHttp.request("POST", "/uploads", uploadTicketSchema, { body: uploadRequestSchema.parse(body) }),
+			/**
+			* 자리 발급 + 바이트 PUT을 한 번에 — 끝나면 `url`이 공개 주소다.
+			*
+			* 용도 제한(확장자·크기)은 서버가 판정하지만, 같은 규칙으로 여기서 먼저 걸러
+			* 큰 파일을 CDN까지 보내고 나서 거절되는 왕복을 없앤다.
+			*/
+			upload: async (file, options) => {
+				const filename = options?.filename ?? (typeof File !== "undefined" && file instanceof File ? file.name : "");
+				if (!filename) throw new ApiError(400, "UPLOAD_FILENAME_REQUIRED", "파일명이 필요합니다");
+				if (file.size === 0) throw new ApiError(400, "EMPTY_FILE", `파일이 비어 있습니다: ${filename}`);
+				const purpose = options?.purpose ?? "description";
+				const rejection = uploadRejection(purpose, filename, file.size);
+				if (rejection) throw new ApiError(rejection.status, rejection.code, rejection.message);
+				const ticket = await storeHttp.request("POST", "/uploads", uploadTicketSchema, { body: uploadRequestSchema.parse({
+					filename,
+					purpose,
+					size: file.size
+				}) });
+				const put = await fetchFn(ticket.uploadUrl, {
+					method: "PUT",
+					headers: { "content-type": file.type || "application/octet-stream" },
+					body: file
+				});
+				if (!put.ok) throw new ApiError(put.status, "UPLOAD_PUT_FAILED", `업로드에 실패했습니다: ${filename}`);
+				return ticket;
+			}
+		},
 		products: {
 			list: (params) => storeHttp.request("GET", "/products", pageSchema(productSummarySchema), { query: params }),
 			get: (productId) => storeHttp.request("GET", path`/products/${productId}`, productSchema),
@@ -2292,6 +2441,16 @@ function createStoreClient(options) {
 				carrierCode,
 				trackingNumber
 			} }),
+			/**
+			* 배송완료 처리 — `DISPATCHED`·`DELIVERING`만 넘어간다. 응답의 `autoDecisionDate`가 자동 구매확정 예정일이다
+			* (스토어 설정 `autoConfirmDays`가 0이면 null).
+			*/
+			markDelivered: (orderItemId, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/delivered`, orderItemSchema, { headers: idempotency(idempotencyKey) }),
+			/** 배송완료 일괄 처리 — 항목별 부분 성공이다 */
+			markDeliveredBulk: (orderItemIds, idempotencyKey) => storeHttp.request("POST", "/order-items/delivered", bulkResultSchema, {
+				body: { orderItemIds },
+				headers: idempotency(idempotencyKey)
+			}),
 			getDelivery: (orderItemId) => storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema)
 		},
 		carriers: { list: () => storeHttp.request("GET", "/carriers", z.array(carrierSchema)) },
@@ -2926,4 +3085,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { ApiError, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_OPTION_GROUPS, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, RESERVED_STORE_CODES, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageUploadResultSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, refreshUserToken, rejectClaimRequestSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };
+export { ApiError, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_VALUES_PER_GROUP, MAX_VARIANTS, PAYMENT_ROUTING_EXCLUSION_CODES, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, RESERVED_STORE_CODES, STORE_CODE_PATTERN, STORE_ROLE_SCOPES, STORE_SCOPE_RESOURCES, STORE_SESSION_KEYS, TOSS_WIDGET_CLIENT_KEY_PATTERN, TOSS_WIDGET_KEY_MESSAGE, TOSS_WIDGET_SECRET_KEY_PATTERN, UPLOAD_PURPOSE_LIMITS, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_HEADERS, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addressChangeRequestListSchema, addressTypeSchema, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiClientListQuerySchema, apiClientSchema, apiClientSecretRotatedSchema, apiClientStatusSchema, apiClientTypeSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, apiTokenCreateRequestSchema, apiTokenCreatedSchema, apiTokenSchema, approveClaimResultSchema, buildAuthorizeUrl, buildQuery, bulkResultSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, clientCredentialsTokenResponseSchema, createPkcePair, createStoreClient, createStoreSession, customerAddressSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, exchangeStoreTokenViaOAuth, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationListQuerySchema, invitationSchema, isReservedStoreCode, isStoreScope, isWebOrigin, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, myAccountSchema, myStoreSchema, oauthClientRegistrationRequestSchema, oauthClientRegistrationResponseSchema, oauthTokenResponseSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionValueRequestSchema, optionValueSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, refreshUserToken, rejectClaimRequestSchema, reviewListQuerySchema, reviewReportResultSchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, scopeAccessSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeTokenResponseSchema, tossPaymentsCredentialsInputSchema, trackingUpdateResultSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, userTokenResponseSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookRedeliverFailedResultSchema, webhookRequestSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema };

package/package.json

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

package/src/client.ts

@@ -1,6 +1,14 @@
 import { z } from "zod";
 import { base64Utf8 } from "./base64";
-import { createHttp, path, type Query, resolveToken, type TokenSource, unwrapData } from "./http";
+import {
+  ApiError,
+  createHttp,
+  path,
+  type Query,
+  resolveToken,
+  type TokenSource,
+  unwrapData,
+} from "./http";
 import {
   type AnalyticsPagesParams,
   type AnalyticsProductsParams,
@@ -173,7 +181,14 @@ import {
   type UpdateStoreRequest,
   updateStoreRequestSchema,
 } from "./schemas/store";
-import { type UploadRequest, uploadRequestSchema, uploadTicketSchema } from "./schemas/upload";
+import {
+  type UploadPurpose,
+  type UploadRequest,
+  type UploadTicket,
+  uploadRejection,
+  uploadRequestSchema,
+  uploadTicketSchema,
+} from "./schemas/upload";
 import type { AuthorizeOptions, StoreSession } from "./session";
 
 export interface StoreClientOptions {
@@ -372,6 +387,44 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.request("POST", "/uploads", uploadTicketSchema, {
           body: uploadRequestSchema.parse(body),
         }),
+      /**
+       * 자리 발급 + 바이트 PUT을 한 번에 — 끝나면 `url`이 공개 주소다.
+       *
+       * 용도 제한(확장자·크기)은 서버가 판정하지만, 같은 규칙으로 여기서 먼저 걸러
+       * 큰 파일을 CDN까지 보내고 나서 거절되는 왕복을 없앤다.
+       */
+      upload: async (
+        file: Blob,
+        options?: { purpose?: UploadPurpose; filename?: string },
+      ): Promise<UploadTicket> => {
+        const filename =
+          options?.filename ??
+          (typeof File !== "undefined" && file instanceof File ? file.name : "");
+        if (!filename) {
+          throw new ApiError(400, "UPLOAD_FILENAME_REQUIRED", "파일명이 필요합니다");
+        }
+        if (file.size === 0) {
+          // 빈 파일은 PUT 자체는 성공하고 0바이트 객체가 공개돼 깨진 이미지로 남는다
+          throw new ApiError(400, "EMPTY_FILE", `파일이 비어 있습니다: ${filename}`);
+        }
+        const purpose = options?.purpose ?? "description";
+        const rejection = uploadRejection(purpose, filename, file.size);
+        if (rejection) {
+          throw new ApiError(rejection.status, rejection.code, rejection.message);
+        }
+        const ticket = await storeHttp.request("POST", "/uploads", uploadTicketSchema, {
+          body: uploadRequestSchema.parse({ filename, purpose, size: file.size }),
+        });
+        const put = await fetchFn(ticket.uploadUrl, {
+          method: "PUT",
+          headers: { "content-type": file.type || "application/octet-stream" },
+          body: file,
+        });
+        if (!put.ok) {
+          throw new ApiError(put.status, "UPLOAD_PUT_FAILED", `업로드에 실패했습니다: ${filename}`);
+        }
+        return ticket;
+      },
     },
 
     products: {
@@ -532,6 +585,20 @@ export function createStoreClient(options: StoreClientOptions) {
         storeHttp.requestVoid("PUT", path`/order-items/${orderItemId}/dispatch/tracking`, {
           body: { carrierCode, trackingNumber },
         }),
+      /**
+       * 배송완료 처리 — `DISPATCHED`·`DELIVERING`만 넘어간다. 응답의 `autoDecisionDate`가 자동 구매확정 예정일이다
+       * (스토어 설정 `autoConfirmDays`가 0이면 null).
+       */
+      markDelivered: (orderItemId: string, idempotencyKey?: string) =>
+        storeHttp.request("POST", path`/order-items/${orderItemId}/delivered`, orderItemSchema, {
+          headers: idempotency(idempotencyKey),
+        }),
+      /** 배송완료 일괄 처리 — 항목별 부분 성공이다 */
+      markDeliveredBulk: (orderItemIds: string[], idempotencyKey?: string) =>
+        storeHttp.request("POST", "/order-items/delivered", bulkResultSchema, {
+          body: { orderItemIds },
+          headers: idempotency(idempotencyKey),
+        }),
       getDelivery: (orderItemId: string) =>
         storeHttp.request("GET", path`/order-items/${orderItemId}/delivery`, deliveryStatusSchema),
     },

package/src/schemas/common.ts

@@ -67,6 +67,9 @@ export const changeTypeSchema = z.enum([
   "CLAIM.CANCEL_REQUESTED",
   "CLAIM.RETURN_REQUESTED",
   "CLAIM.EXCHANGE_REQUESTED",
+  // 취소·반품 승인으로 주문상품이 취소됐다 — 서버가 이 값을 쓰므로 목록에 있어야 한다
+  // (빠져 있던 동안 클레임이 끝난 주문상품이 섞이면 응답 검증이 깨졌다)
+  "CLAIM.COMPLETED",
   "ORDER.ADDRESS_CHANGE_REQUESTED",
 ]);
 

package/src/schemas/product.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
+import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
 
@@ -96,6 +97,62 @@ export const productSchema = productSummarySchema.extend({
 
 export type Product = z.infer<typeof productSchema>;
 
+/** 상품 하나에 등록할 수 있는 이미지 최대 장수 — 첫 장이 대표(썸네일)다 */
+export const MAX_PRODUCT_IMAGES = 10;
+
+/**
+ * 상품 이미지 주소의 와이어 형식 — URL이고 2048자 이하다.
+ *
+ * https·확장자 규칙은 여기서 강제하지 않고 `productImageRejection`이 판정한다. 서버가
+ * **새로 추가된 주소에만** 그 규칙을 적용해야 하기 때문이다(규칙이 생기기 전에 저장된
+ * 주소 하나로 상품 수정 전체가 막히면 셀러가 빠져나갈 길이 없다).
+ *
+ * 응답 스키마(`productSchema.images`)도 넓게 둔다. 과거에 저장된 주소를 파싱 오류로
+ * 만들면 상품 조회 자체가 막힌다.
+ */
+export const productImageUrlSchema = z
+  .url()
+  .max(2048)
+  .describe("상품 이미지 주소. https만 허용하고, 확장자가 있으면 이미지 형식이어야 한다");
+
+export interface ProductImageRejection {
+  code: "INVALID_IMAGE_URL" | "UNSUPPORTED_FILE_TYPE";
+  message: string;
+}
+
+/**
+ * 상품에 **새로 붙이는** 이미지 주소의 규칙. 통과하면 `null`.
+ *
+ * - https만 받는다. http는 https 스토어프론트에서 혼합 콘텐츠로 차단되고 `data:`·`javascript:`는
+ *   상세 화면에 박히는 주입 경로가 된다.
+ * - 호스트는 제한하지 않는다 — 셀러가 이미 쓰는 이미지 호스트를 그대로 붙일 수 있어야 한다.
+ * - 경로에 확장자가 있으면 상품 이미지 형식이어야 한다(svg·동영상 거부). **확장자가 없으면 통과시킨다**
+ *   — 외부 이미지 CDN은 확장자 없는 키를 쓰는 경우가 흔하고, 주소만으로는 실제 형식을 알 수 없다.
+ */
+export function productImageRejection(url: string): ProductImageRejection | null {
+  if (url.length > 2048) {
+    return { code: "INVALID_IMAGE_URL", message: "이미지 주소가 너무 깁니다" };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { code: "INVALID_IMAGE_URL", message: "이미지 주소 형식이 아닙니다" };
+  }
+  if (parsed.protocol !== "https:") {
+    return { code: "INVALID_IMAGE_URL", message: "이미지 주소는 https로 시작해야 합니다" };
+  }
+  const extension = uploadExtensionOf(parsed.pathname);
+  const allowed = UPLOAD_PURPOSE_LIMITS["product-image"].extensions;
+  if (extension && !allowed.includes(extension)) {
+    return {
+      code: "UNSUPPORTED_FILE_TYPE",
+      message: `상품 이미지는 ${allowed.join(", ")}만 쓸 수 있습니다`,
+    };
+  }
+  return null;
+}
+
 /** 옵션 축(그룹) 최대 개수 — 스키마 상한의 단일 원천 */
 export const MAX_OPTION_GROUPS = 3;
 /** 축 하나가 가질 수 있는 값의 최대 개수 */
@@ -212,7 +269,12 @@ export const productCreateRequestSchema = z
      * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
      */
     descriptionJson: z.string().nullable().optional(),
-    images: z.array(z.url()).min(1).max(10).optional(),
+    images: z
+      .array(productImageUrlSchema)
+      .min(1)
+      .max(MAX_PRODUCT_IMAGES)
+      .optional()
+      .describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
     attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
     deliveryType: deliveryTypeSchema
       .default("PAID")
@@ -276,13 +338,6 @@ export const productListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
-/** `POST /v1/product-images` 응답 — 업로드된 이미지의 CDN 주소 */
-export const productImageUploadResultSchema = z.object({
-  images: z.array(z.object({ url: z.url(), width: z.number().int(), height: z.number().int() })),
-});
-
-export type ProductImageUploadResult = z.infer<typeof productImageUploadResultSchema>;
-
 export const discountSchema = z.object({
   productId: z.string(),
   discountType: z.enum(["RATE", "AMOUNT"]),

package/src/schemas/store.ts

@@ -102,6 +102,17 @@ export const analyticsOriginSchema = z
 /** 허용 오리진 상한 */
 export const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 
+/** 자동 배송완료·자동 구매확정 대기일 상한 */
+export const MAX_AUTO_TRANSITION_DAYS = 30;
+
+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 +143,20 @@ 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),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -156,6 +181,8 @@ export const storeSchema = z.object({
       "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+  autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
+  autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
   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>;