@sayren/store-sdk 0.29.4 → 0.29.6

package/dist/index.mjs

@@ -730,6 +730,31 @@ const categoryListQuerySchema = z.object({
 /** `DELETE /v1/categories/{categoryId}` 쿼리 — OpenAPI 문서용 형태 */
 const categoryDeleteQuerySchema = z.object({ strategy: categoryDeleteStrategySchema.optional().describe("하위 카테고리·연결 상품 처리 방식. 생략하면 둘 중 하나라도 있을 때 409 `CATEGORY_NOT_EMPTY`다. `reparent`는 직계 자식을 삭제할 카테고리의 부모로 옮기고, `cascade`는 서브트리를 삭제하고 연결 상품을 미분류로 둔다") });
 //#endregion
+//#region src/schemas/commerce-number.ts
+/**
+* 국내 쇼핑몰 번호 체계(이슈 #107) — 공개 ID(`ord_…` 등)와 따로 싣는 숫자 번호의 표기·필드.
+* 번호는 서버가 만들고 생성 후 바뀌지 않는다. 새 필드라 옛 서버 응답에는 없다 — 파싱은 null로 채운다.
+*/
+/**
+* 번호 표기 — 숫자를 앞에서부터 4자리씩 하이픈으로 나눈다. 주문번호 `26100284731592` → `2610-0284-7315-92`,
+* 상품주문번호 `2610028473159201` → `2610-0284-7315-9201`. 숫자만으로 된 값이 아니면(클레임번호 `C…`) 그대로, 없으면 빈 문자열이다.
+* 화면 표기 전용이다 — API에 보낼 때는 원래 값을 쓴다(주문번호 조회는 하이픈도 받는다)
+*/
+function formatOrderNo(no) {
+	if (!no) return "";
+	if (!/^\d+$/.test(no)) return no;
+	return no.match(/.{1,4}/g)?.join("-") ?? no;
+}
+/** 표기 하이픈·공백을 지운 숫자 번호. 숫자가 아닌 글자가 남거나 비면 null */
+function parseOrderNo(value) {
+	const digits = value.replace(/[\s-]/g, "");
+	return /^\d+$/.test(digits) ? digits : null;
+}
+/** 응답 번호 필드 — 서버는 항상 싣고, 번호 체계 이전 행(백필 전)·옛 서버 응답은 null이다 */
+function commerceNumberField(description) {
+	return z.string().nullable().optional().default(null).describe(description);
+}
+//#endregion
 //#region src/schemas/common.ts
 const pageInfoSchema = z.object({
 	page: z.number().int(),
@@ -826,6 +851,7 @@ const claimReturnAddressSchema = z.object({
 });
 const claimSchema = z.object({
 	claimId: z.string(),
+	claimNo: commerceNumberField("클레임번호(이슈 #107) — `C` + YYMMDD(KST) + 숫자 8자리. 취소·반품·교환 접수 단위 번호이고 생성 후 바뀌지 않습니다"),
 	type: claimTypeSchema,
 	status: claimStatusSchema,
 	orderId: z.string(),
@@ -1545,6 +1571,7 @@ const productStatusSchema = z.enum([
 ]);
 const productSummarySchema = z.object({
 	productId: z.string(),
+	productNo: z.number().int().nullable().optional().default(null).describe("상품번호(이슈 #107) — 상점별 1부터 증가하는 숫자, 상점 안에서 유일, 생성 후 바뀌지 않으며 지운 상품의 번호는 다시 쓰지 않습니다. URL에 써도 됩니다(스토어프론트 상품 상세 경로가 받습니다). 번호 체계 이전 응답은 null"),
 	name: z.string(),
 	status: productStatusSchema,
 	salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
@@ -1578,6 +1605,7 @@ const optionGroupSchema = z.object({
 */
 const productVariantSchema = z.object({
 	variantId: z.string(),
+	variantNo: z.string().nullable().optional().default(null).describe("조합 번호(이슈 #107) — `{productNo}-{조합 순번 2자리}`(예: `10482-03`). 시스템이 매기는 SKU이고 상점 안에서 유일합니다(상품번호가 상점 범위라 다른 상점과는 겹칠 수 있습니다). 생성 후 바뀌지 않으며, 지운 조합의 번호는 다시 쓰지 않습니다. 셀러가 입력하는 `sku`와 별개입니다"),
 	/** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
 	valueIds: z.array(z.string()),
 	/** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
@@ -1937,6 +1965,7 @@ const productListQuerySchema = z.object({
 	categoryId: z.string().optional().describe("카테고리 필터 — 하위 카테고리의 상품도 포함"),
 	keyword: z.string().optional().describe("상품명 검색 (포함)"),
 	sellerCode: z.string().optional().describe("판매자 상품코드 — 이 코드가 붙은 variant를 가진 상품"),
+	productNo: z.string().optional().describe("상품번호(이슈 #107) — 이 상점의 그 번호 상품만. 숫자가 아니면 400 `INVALID_PARAMETER`"),
 	sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
 	...pageQueryShape()
 });
@@ -2730,8 +2759,10 @@ function quotePricing(input) {
 	};
 }
 /**
-* 사용 적립금 금액(순수) — 요청·잔액·최대 비율·「결제 금액 100원 남기기」 중 작은 값을 단위로 내린다.
-* 최소 보유액·최소 사용액에 못 미치면 0이다. 결제 금액이 0원이 되는 사용(적립금 전액 결제)은 아직 받지 않는다(P4).
+* 사용 적립금 금액(순수) — 요청·잔액·최대 비율 중 작은 값을 쓴다(#93 P3·P4).
+* - 결제 금액 전체를 덮을 수 있으면 전액을 쓴다(0원 결제, 이때만 사용 단위를 보지 않는다)
+* - 그 밖에는 사용 단위로 내리고, 남는 결제 금액이 1~99원이면 적립금을 줄여 100원을 남긴다(`MIN_PAYMENT`)
+* 최소 보유액·최소 사용액에 못 미치면 0이다.
 */
 function pointUseOf(points, amounts) {
 	const none = {
@@ -2745,12 +2776,29 @@ function pointUseOf(points, amounts) {
 	const unit = Math.max(1, Math.floor(rules.unit));
 	const base = amounts.productPaid + (rules.includeDeliveryFee ? amounts.deliveryPaid : 0);
 	const byRatio = Math.floor(base * rules.maxRatioBp / 1e4);
-	const byPayment = Math.max(0, amounts.total - 100);
 	const balance = Math.max(0, points.balance);
+	const total = Math.max(0, amounts.total);
 	const floorUnit = (value) => Math.floor(Math.max(0, value) / unit) * unit;
+	/** 상한 `cap`으로 쓸 수 있는 금액 — 전액이면 0원 결제, 아니면 단위 내림 + 100원 남기기 */
+	const usableWithin = (cap) => {
+		if (total > 0 && cap >= total) return {
+			amount: total,
+			adjusted: false
+		};
+		const amount = floorUnit(Math.min(cap, total));
+		const remaining = total - amount;
+		if (remaining > 0 && remaining < 100) return {
+			amount: floorUnit(total - 100),
+			adjusted: true
+		};
+		return {
+			amount,
+			adjusted: false
+		};
+	};
 	const eligible = balance >= rules.minBalance;
-	const ceiling = Math.min(balance, byRatio, byPayment);
-	const maxUsable = eligible && floorUnit(ceiling) >= rules.minAmount ? floorUnit(ceiling) : 0;
+	const ceiling = usableWithin(Math.min(balance, byRatio)).amount;
+	const maxUsable = eligible && ceiling > 0 && ceiling >= rules.minAmount ? ceiling : 0;
 	const requested = Math.max(0, Math.floor(points.requested));
 	if (requested === 0) return {
 		...none,
@@ -2762,23 +2810,23 @@ function pointUseOf(points, amounts) {
 		adjustReason: null,
 		rejectReason: "MIN_BALANCE"
 	};
-	const amount = floorUnit(Math.min(requested, balance, byRatio, byPayment));
-	if (amount <= 0) return {
+	const used = usableWithin(Math.min(requested, balance, byRatio));
+	if (used.amount <= 0) return {
 		amount: 0,
 		maxUsable,
 		adjustReason: null,
 		rejectReason: "NOT_PAYABLE"
 	};
-	if (amount < rules.minAmount) return {
+	if (used.amount < rules.minAmount) return {
 		amount: 0,
 		maxUsable,
 		adjustReason: null,
 		rejectReason: "MIN_AMOUNT"
 	};
 	return {
-		amount,
+		amount: used.amount,
 		maxUsable,
-		adjustReason: floorUnit(Math.min(requested, balance, byRatio)) > amount ? "MIN_PAYMENT" : null,
+		adjustReason: used.adjusted ? "MIN_PAYMENT" : null,
 		rejectReason: null
 	};
 }
@@ -3947,7 +3995,8 @@ const paymentRecordSchema = z.object({
 	environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
 	testPayment: z.boolean().describe("샌드박스 결제인가"),
 	pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
-	attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
+	attemptId: z.string().nullable().describe("대표 시도 id. 번호 체계(이슈 #107) 이전 시도는 이 값을 PG 주문번호로 보냈습니다"),
+	pgOrderId: z.string().nullable().optional().default(null).describe("PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다"),
 	attemptCount: z.number().int().describe("시도 횟수"),
 	failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
 	failMessage: z.string().nullable().describe("실패 사유"),
@@ -3958,6 +4007,7 @@ const paymentRecordSchema = z.object({
 const paymentRecordPageSchema = pageSchema(paymentRecordSchema);
 const paymentAttemptRecordSchema = z.object({
 	attemptId: z.string(),
+	pgOrderId: z.string().nullable().optional().default(null).describe("PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다"),
 	sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
 	provider: pgProviderSchema,
 	status: paymentAttemptStatusSchema,
@@ -3998,7 +4048,7 @@ const paymentListQuerySchema = z.object({
 	status: z.string().optional().describe("결제 상태 필터 (PaymentRecordStatus)"),
 	provider: z.string().optional().describe("PG 필터"),
 	method: z.string().optional().describe("실제 결제수단 필터"),
-	keyword: z.string().optional().describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
+	keyword: z.string().optional().describe("결제 id·주문 id·PG 거래 id·시도 id·PG 주문번호(일치), 구매자명(포함)"),
 	includeTest: z.string().optional().describe("테스트 결제 포함 여부 (`true`·`false`. 기본 false — 실결제만)"),
 	page: z.string().optional().describe("페이지 번호 (1부터)"),
 	size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)")
@@ -4007,6 +4057,7 @@ const paymentListQuerySchema = z.object({
 //#region src/schemas/order.ts
 const orderSummarySchema = z.object({
 	orderId: z.string(),
+	orderNo: commerceNumberField("주문번호(이슈 #107) — 숫자 14자리(YYMMDD KST + 난수 8자리), 전역 유일, 생성 후 바뀌지 않습니다. 전화 CS·ARS용 번호이고 API 경로의 식별자는 여전히 `orderId`입니다. 화면 표기는 `formatOrderNo`(4자리 하이픈)를 쓰십시오"),
 	ordererName: z.string(),
 	itemCount: z.number().int(),
 	totalAmount: z.number().int(),
@@ -4032,6 +4083,7 @@ const orderItemFulfillmentSchema = z.object({
 });
 const orderItemSchema = z.object({
 	orderItemId: z.string(),
+	orderItemNo: commerceNumberField("상품주문번호(이슈 #107) — 주문번호 + 줄 순번 2자리(01부터, 100줄부터 3자리). 부분 취소·클레임·송장의 처리 단위 번호이고 생성 후 바뀌지 않습니다"),
 	orderId: z.string(),
 	status: orderItemStatusSchema,
 	claimStatus: z.enum([
@@ -4077,6 +4129,7 @@ const orderDiscountSchema = z.object({
 });
 const orderSchema = z.object({
 	orderId: z.string(),
+	orderNo: commerceNumberField("주문번호(이슈 #107) — 숫자 14자리(YYMMDD KST + 난수 8자리), 전역 유일, 생성 후 바뀌지 않습니다. 전화 CS·ARS용 번호이고 API 경로의 식별자는 여전히 `orderId`입니다. 화면 표기는 `formatOrderNo`(4자리 하이픈)를 쓰십시오"),
 	orderedAt: z.string(),
 	orderer: z.object({
 		name: z.string(),
@@ -4118,14 +4171,15 @@ const testPaymentQuery = z.enum(["true", "false"]).optional().describe("테스
 const pageQuery = { page: z.string().optional().describe("페이지 번호 (1부터, 기본 1)") };
 /**
 * `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
-* `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+* `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
 * `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
 */
 const orderListQuerySchema = z.object({
-	orderedFrom: z.string().describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). 필수"),
+	orderedFrom: z.string().optional().describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). `orderNo`가 없으면 필수"),
 	orderedTo: z.string().optional().describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
 	status: orderItemStatusSchema.optional().describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
-	keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+	keyword: z.string().optional().describe("주문 id·주문번호(일치, 하이픈 허용)·주문자명·수령인명(포함) 검색"),
+	orderNo: z.string().optional().describe("주문번호 조회(이슈 #107) — 숫자 14자리, 하이픈 허용(`2610-0284-7315-92`). 주면 기간 조건 없이 그 주문만 찾습니다. 형식이 아니면 400 `INVALID_PARAMETER`"),
 	fulfillmentType: z.string().optional().describe("상품 유형 필터(이슈 #48) — 이 유형(`SHIPPING`·`MANUAL`)의 주문상품이 하나라도 있는 주문"),
 	testPayment: testPaymentQuery,
 	...pageQuery,
@@ -7118,6 +7172,7 @@ const envelopeFields = {
 };
 const orderWebhookEventDataSchema = z.object({
 	orderId: z.string().describe("주문 ID"),
+	orderNo: z.string().nullable().optional().default(null).describe("주문번호(이슈 #107) — 숫자 14자리. 이 필드가 없는 이전 이벤트와 번호 체계 이전 주문은 null로 읽는다"),
 	status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
 	testPayment: z.boolean().optional().default(false).describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다"),
 	couponDiscountAmount: z.number().int().optional().default(0).describe("주문이 받은 상품·주문 쿠폰 할인 합계 (원). 즉시할인(`discountAmount`)과 별개다. 쿠폰이 없거나 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
@@ -7136,6 +7191,7 @@ const orderWebhookEventDataSchema = z.object({
 */
 const orderFulfilledWebhookEventDataSchema = z.object({
 	orderId: z.string().describe("주문 ID"),
+	orderNo: z.string().nullable().optional().default(null).describe("주문번호(이슈 #107) — 숫자 14자리. 이 필드가 없는 이전 이벤트와 번호 체계 이전 주문은 null로 읽는다"),
 	orderItemId: z.string().describe("제공한 주문상품 ID"),
 	status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
 	fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe("제공한 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57)"),
@@ -7150,6 +7206,7 @@ const orderFulfilledWebhookEventDataSchema = z.object({
 */
 const orderCanceledWebhookEventDataSchema = z.object({
 	orderId: z.string().describe("주문 ID"),
+	orderNo: z.string().nullable().optional().default(null).describe("주문번호(이슈 #107) — 숫자 14자리. 이 필드가 없는 이전 이벤트와 번호 체계 이전 주문은 null로 읽는다"),
 	orderItemId: z.string().describe("취소한 주문 상품 ID"),
 	status: orderItemStatusSchema.describe("취소 뒤 주문 대표 상태. 모든 주문 상품이 취소됐으면 `CANCELED`다"),
 	itemStatus: orderItemStatusSchema.describe("취소 뒤 주문 상품 상태. 전 수량이 취소됐으면 `CANCELED`, 일부만 취소했으면 원래 상태다"),
@@ -7166,6 +7223,7 @@ const orderCanceledWebhookEventDataSchema = z.object({
 });
 const claimWebhookEventDataSchema = z.object({
 	claimId: z.string().describe("클레임 ID"),
+	claimNo: z.string().nullable().optional().default(null).describe("클레임번호(이슈 #107) — `C` + YYMMDD + 숫자 8자리. 이 필드가 없는 이전 이벤트와 번호 체계 이전 클레임은 null로 읽는다"),
 	orderId: z.string().describe("주문 ID"),
 	orderItemId: z.string().describe("클레임 대상 주문 상품 ID"),
 	claimType: claimTypeSchema.describe("클레임 유형"),
@@ -7430,4 +7488,4 @@ function createStoreSession(options) {
 	};
 }
 //#endregion
-export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, BUSINESS_INFO_MAX_LENGTH, BUSINESS_NUMBER_PATTERN, CASH_RECEIPT_STATUS_VALUES, COLLECTION_BEST_SELLING_DAYS, COLLECTION_PREVIEW_SIZE, COLLECTION_PRODUCT_SORTS, COLLECTION_SALES_SORT_DEFAULT_DAYS, COLLECTION_SLUG_PATTERN, COLLECTION_TYPES, COUPON_CODE_PATTERN, COUPON_CONDITIONS_DEFAULTS, COUPON_TARGET_ALL, COUPON_TARGET_LIST_MAX, CUSTOM_INPUT_FORBIDDEN_WORDS, FULFILLMENT_RULES, MAX_ADDON_GROUPS, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_COLLECTIONS, MAX_COLLECTION_BEST_SELLING_TOP, MAX_COLLECTION_CREATED_WITHIN_DAYS, MAX_COLLECTION_DESCRIPTION, MAX_COLLECTION_PRODUCTS, MAX_COLLECTION_PRODUCTS_PER_ADD, MAX_COLLECTION_RULES, MAX_COLLECTION_RULE_CATEGORIES, MAX_COLLECTION_TITLE, MAX_CUSTOM_INPUTS, MAX_CUSTOM_INPUT_LENGTH, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_SAVED_OPTION_SETS, MAX_SAVED_OPTION_SET_NAME, MAX_VALUES_PER_GROUP, MAX_VARIANTS, MCP_TELEMETRY_MAX_RESULTS, MIN_PAYMENT_AMOUNT, NO_COUPON_SETTLEMENT, NO_SHIPPING_BUNDLE_KEY, PAYMENT_ROUTING_EXCLUSION_CODES, POINT_ADJUSTMENT_MAX, POINT_EARN_RATE_BP_MAX, POINT_ENTRY_TYPES, POINT_EXPIRY_DAYS_MAX, POINT_EXPIRY_DAYS_MIN, POINT_LOT_SOURCES, POINT_POLICY_DEFAULTS, POINT_REVIEW_REWARD_MAX, POINT_USE_UNITS, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, REFUND_POLICY_DEFAULTS, REFUND_POLICY_DELIVERY_FEE_KEYS, REMOTE_AREA_ZIP_RANGES, RESERVED_STOREFRONT_SLUGS, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STOREFRONT_BLOCKED_PATH_SEGMENTS, STOREFRONT_BUILD_STAGES, STOREFRONT_BUILD_TERMINAL_STATUSES, STOREFRONT_CHECK_TERMINAL_STATUSES, STOREFRONT_CUSTOM_DOMAIN_LIMIT_DEFAULT, STOREFRONT_DOMAIN_DNS_GRACE_DAYS, STOREFRONT_DOMAIN_DNS_WAIT_DAYS, STOREFRONT_DOMAIN_TXT_LABEL, STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES, STOREFRONT_EDIT_CAPACITY, STOREFRONT_EDIT_IDLE_MINUTES, STOREFRONT_EDIT_PREVIEW_SUFFIX, STOREFRONT_EDIT_START_STAGES, STOREFRONT_FILE_BATCH_MAX, STOREFRONT_FILE_MAX_BYTES, STOREFRONT_PATH_SEGMENT_PATTERN, STOREFRONT_PLATFORM_DOMAINS, STOREFRONT_PUBLIC_SUFFIXES, STOREFRONT_SEARCH_REGEX_MAX_LENGTH, STOREFRONT_SHOWCASE_SLUG_PREFIX, STOREFRONT_SITE_CREATE_LIMIT, STOREFRONT_SLUG_CHANGE_LIMIT, STOREFRONT_SLUG_CHANGE_WINDOW_DAYS, STOREFRONT_SLUG_HOLD_DAYS, STOREFRONT_SLUG_PATTERN, STOREFRONT_SOURCE_BLOB_BATCH_MAX, STOREFRONT_SOURCE_PART_BYTES, STOREFRONT_WORKSPACE_MAX_BYTES, STOREFRONT_WORKSPACE_MAX_FILES, 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_COUNT_WARNING, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_FAILURE_REASONS, WEBHOOK_HEADERS, WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES, WEBHOOK_RESOURCE_TYPES, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addStorefrontDomainRequestSchema, addonGroupRequestSchema, addonGroupSchema, addonValueRequestSchema, addonValueSchema, addressChangeRequestListSchema, addressTypeSchema, agentPolicyDecisionSchema, allocateByWeight, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, bestSellingRuleOf, buildAuthorizeUrl, buildQuery, bulkResultSchema, businessInfoPatchShape, businessInfoResponseShape, businessNumberSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeStorefrontSlugRequestSchema, changeStorefrontTemplateRequestSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, collectionCreateRequestSchema, collectionListQuerySchema, collectionPageSchema, collectionPatchRequestSchema, collectionPreviewRequestSchema, collectionPreviewSchema, collectionProductListQuerySchema, collectionProductSchema, collectionProductSortRequestSchema, collectionProductsAddRequestSchema, collectionProductsReplaceRequestSchema, collectionRuleCategoryIds, collectionRuleSchema, collectionRuleViewSchema, collectionRulesPredicate, collectionRulesSchema, collectionSchema, collectionStateCountsSchema, collectionStateOf, collectionStateSchema, compareBySales, consentActionSchema, consentKindSchema, consentSourceSchema, couponBenefitSchema, couponConditionsInputSchema, couponConditionsSchema, couponDiscountOf, couponIssueListQuerySchema, couponIssueMethodSchema, couponIssueSchema, couponIssueStatusSchema, couponKindSchema, couponListQuerySchema, couponRedemptionListQuerySchema, couponRedemptionSchema, couponRejectReasonSchema, couponRuleSchema, couponSchema, couponStatsSchema, couponStatusSchema, couponTargetInputSchema, couponTargetSchema, createCouponRequestSchema, createPkcePair, createStoreClient, createStoreSession, createStorefrontEditPreviewLinkRequestSchema, createStorefrontPreviewLinkRequestSchema, createStorefrontSiteRequestSchema, createStorefrontVersionRequestSchema, customInputLabelForbiddenWord, customInputRequestSchema, customInputSchema, customInputValueSchema, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerCouponSchema, customerDelegationRequestSchema, customerDelegationSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerPointsSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deleteStorefrontFileRequestSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, descendantCategoryIdsOf, disableStorefrontHostingRequestSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, fulfillBulkRequestSchema, fulfillRequestSchema, fulfillmentRuleOf, fulfillmentTypeOf, fulfillmentTypeResponseSchema, fulfillmentTypeSchema, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isCouponTargetLine, isEditableStorefrontPath, isReservedStoreCode, isReservedStorefrontSlug, isShowcaseStorefrontSlug, isStoreScope, isWebOrigin, issueCouponRequestSchema, issueCouponResultSchema, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, matchesCollectionRules, mcpRuleResultSchema, mcpToolEventSchema, moveStorefrontFileRequestSchema, myAccountSchema, myStoreSchema, normalizeBusinessNumber, normalizeCouponCode, normalizeStorefrontHostname, normalizeStorefrontPath, oauthTokenResponseSchema, openFulfillmentUnion, optionGroupKindSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionSelectionSchema, optionSortSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderDiscountSchema, orderFulfilledWebhookEventDataSchema, orderFulfilledWebhookEventSchema, orderItemFulfillmentSchema, orderItemFulfillmentSnapshotResponseSchema, orderItemFulfillmentSnapshotSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentFailureWarningSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, planCodeSchema, planEntitlementsSchema, planErrorDetailsSchema, pointAdjustmentRequestSchema, pointAdjustmentResultSchema, pointEarnOf, pointEarnRateBpSchema, pointEarningEnabled, pointEntrySchema, pointExpiresAtOf, pointHistoryQuerySchema, pointLotSchema, pointPolicyNoticeSchema, pointPolicySchema, pointRestoreExpiresAtOf, pointUseOf, pointUsePolicySchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productFulfillmentCreateSchema, productFulfillmentResponseSchema, productFulfillmentSchema, productFulfillmentUpdateSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productRefundPolicyPatchSchema, productReplaceRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedPaidRefundBase, proratedPointRefund, proratedRefundBase, publicPlanSchema, publicPlansSchema, publishStorefrontVersionRequestSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, purchaseEarnPolicySchema, purchaseEarnRateOf, quoteDelivery, quotePricing, rankBestSelling, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, replaceStorefrontSourceRequestSchema, requiresCollection, requiresShipping, resolvePointPolicy, resolveRefundPolicy, resolveShippingPolicy, responsePlanCodeSchema, responsePointEntryTypeSchema, reviewListQuerySchema, reviewReportResultSchema, reviewRewardPointOf, reviewRewardPolicySchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, rollbackStorefrontRequestSchema, runStorefrontCheckRequestSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, savedCustomInputRequestSchema, savedCustomInputSchema, savedOptionGroupRequestSchema, savedOptionGroupSchema, savedOptionSetCompositionSchema, savedOptionSetFromProductRequestSchema, savedOptionSetFromProductResultSchema, savedOptionSetListQuerySchema, savedOptionSetRequestSchema, savedOptionSetSchema, savedOptionSetSortSchema, savedOptionValueRequestSchema, savedOptionValueSchema, scopeAccessSchema, searchStorefrontFilesRequestSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, setStorefrontVisibilityRequestSchema, settleCouponShortfall, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, splitRefund, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storePointPolicySchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeSubscriptionSchema, storefrontBuildDependenciesSchema, storefrontBuildListQuerySchema, storefrontBuildSchema, storefrontBuildStatusSchema, storefrontCheckSchema, storefrontCheckStatusSchema, storefrontCustomDomainStatusSchema, storefrontCustomHostnameProblem, storefrontDependencyFindingSchema, storefrontDeploymentLogSchema, storefrontDeploymentSchema, storefrontDeploymentStepSchema, storefrontDnsRecordSchema, storefrontDomainSchema, storefrontDomainTxtNameOf, storefrontEditPreviewLabelOf, storefrontEditPreviewSchema, storefrontEditSessionSchema, storefrontEditSessionStatusSchema, storefrontEditingSchema, storefrontFileConflictDetailsSchema, storefrontFileContentQuerySchema, storefrontFileContentSchema, storefrontFileDeleteResultSchema, storefrontFileEncodingSchema, storefrontFileEntrySchema, storefrontFileHashSchema, storefrontFileListQuerySchema, storefrontFileListSchema, storefrontFileMoveResultSchema, storefrontFilePathSchema, storefrontFileSearchResultSchema, storefrontFileWriteResultSchema, storefrontHostingSchema, storefrontPreviewLinkSchema, storefrontProvisioningSchema, storefrontRuleResultSchema, storefrontRuleSeveritySchema, storefrontSiteDomainSchema, storefrontSiteDomainsSchema, storefrontSiteSchema, storefrontSiteStatusSchema, storefrontSlugAvailabilityQuerySchema, storefrontSlugAvailabilitySchema, storefrontSlugSchema, storefrontSourceArchivePartSchema, storefrontSourceArchiveQuerySchema, storefrontSourceBlobsResultSchema, storefrontSourceModeSchema, storefrontSourceRefSchema, storefrontSourceReplacedSchema, storefrontSourceSchema, storefrontSuspensionSchema, storefrontTemplateSchema, storefrontVerifyReportSchema, storefrontVersionCreatedSchema, storefrontVersionSchema, storefrontVersionStatusSchema, storefrontVisibilitySchema, subscriptionLimitsSchema, subscriptionStatusSchema, subscriptionUsageSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateCouponRequestSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updatePointPolicyRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadStorefrontSourceBlobsRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema, writeStorefrontFilesRequestSchema };
+export { APPROVAL_ALREADY_DECIDED_CODE, APPROVAL_REQUIRED_CODE, ApiError, ApprovalPendingError, BUSINESS_INFO_MAX_LENGTH, BUSINESS_NUMBER_PATTERN, CASH_RECEIPT_STATUS_VALUES, COLLECTION_BEST_SELLING_DAYS, COLLECTION_PREVIEW_SIZE, COLLECTION_PRODUCT_SORTS, COLLECTION_SALES_SORT_DEFAULT_DAYS, COLLECTION_SLUG_PATTERN, COLLECTION_TYPES, COUPON_CODE_PATTERN, COUPON_CONDITIONS_DEFAULTS, COUPON_TARGET_ALL, COUPON_TARGET_LIST_MAX, CUSTOM_INPUT_FORBIDDEN_WORDS, FULFILLMENT_RULES, MAX_ADDON_GROUPS, MAX_ANALYTICS_ALLOWED_ORIGINS, MAX_AUTO_TRANSITION_DAYS, MAX_COLLECTIONS, MAX_COLLECTION_BEST_SELLING_TOP, MAX_COLLECTION_CREATED_WITHIN_DAYS, MAX_COLLECTION_DESCRIPTION, MAX_COLLECTION_PRODUCTS, MAX_COLLECTION_PRODUCTS_PER_ADD, MAX_COLLECTION_RULES, MAX_COLLECTION_RULE_CATEGORIES, MAX_COLLECTION_TITLE, MAX_CUSTOM_INPUTS, MAX_CUSTOM_INPUT_LENGTH, MAX_OPTION_GROUPS, MAX_PRODUCT_IMAGES, MAX_SAVED_OPTION_SETS, MAX_SAVED_OPTION_SET_NAME, MAX_VALUES_PER_GROUP, MAX_VARIANTS, MCP_TELEMETRY_MAX_RESULTS, MIN_PAYMENT_AMOUNT, NO_COUPON_SETTLEMENT, NO_SHIPPING_BUNDLE_KEY, PAYMENT_ROUTING_EXCLUSION_CODES, POINT_ADJUSTMENT_MAX, POINT_EARN_RATE_BP_MAX, POINT_ENTRY_TYPES, POINT_EXPIRY_DAYS_MAX, POINT_EXPIRY_DAYS_MIN, POINT_LOT_SOURCES, POINT_POLICY_DEFAULTS, POINT_REVIEW_REWARD_MAX, POINT_USE_UNITS, PORTONE_CHANNEL_NAME_MAX_LENGTH, PORTONE_MAX_CHANNELS, PORTONE_MIN_CHANNELS, REFUND_POLICY_DEFAULTS, REFUND_POLICY_DELIVERY_FEE_KEYS, REMOTE_AREA_ZIP_RANGES, RESERVED_STOREFRONT_SLUGS, RESERVED_STORE_CODES, SHIPPING_POLICY_DEFAULTS, STOREFRONT_BLOCKED_PATH_SEGMENTS, STOREFRONT_BUILD_STAGES, STOREFRONT_BUILD_TERMINAL_STATUSES, STOREFRONT_CHECK_TERMINAL_STATUSES, STOREFRONT_CUSTOM_DOMAIN_LIMIT_DEFAULT, STOREFRONT_DOMAIN_DNS_GRACE_DAYS, STOREFRONT_DOMAIN_DNS_WAIT_DAYS, STOREFRONT_DOMAIN_TXT_LABEL, STOREFRONT_EDIT_ACTIVITY_TIMEOUT_MINUTES, STOREFRONT_EDIT_CAPACITY, STOREFRONT_EDIT_IDLE_MINUTES, STOREFRONT_EDIT_PREVIEW_SUFFIX, STOREFRONT_EDIT_START_STAGES, STOREFRONT_FILE_BATCH_MAX, STOREFRONT_FILE_MAX_BYTES, STOREFRONT_PATH_SEGMENT_PATTERN, STOREFRONT_PLATFORM_DOMAINS, STOREFRONT_PUBLIC_SUFFIXES, STOREFRONT_SEARCH_REGEX_MAX_LENGTH, STOREFRONT_SHOWCASE_SLUG_PREFIX, STOREFRONT_SITE_CREATE_LIMIT, STOREFRONT_SLUG_CHANGE_LIMIT, STOREFRONT_SLUG_CHANGE_WINDOW_DAYS, STOREFRONT_SLUG_HOLD_DAYS, STOREFRONT_SLUG_PATTERN, STOREFRONT_SOURCE_BLOB_BATCH_MAX, STOREFRONT_SOURCE_PART_BYTES, STOREFRONT_WORKSPACE_MAX_BYTES, STOREFRONT_WORKSPACE_MAX_FILES, 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_COUNT_WARNING, VARIANT_STOCK_EXCLUSIVE_MESSAGE, WEBHOOK_DEFAULT_TOLERANCE_SEC, WEBHOOK_DELIVERY_ID_HEADER, WEBHOOK_EVENT_ID_HEADER, WEBHOOK_EVENT_TYPE_HEADER, WEBHOOK_FAILURE_REASONS, WEBHOOK_HEADERS, WEBHOOK_PAYLOAD_EXCERPT_MAX_BYTES, WEBHOOK_RESOURCE_TYPES, WEBHOOK_SIGNATURE_HEADER, WEBHOOK_USER_AGENT, addStorefrontDomainRequestSchema, addonGroupRequestSchema, addonGroupSchema, addonValueRequestSchema, addonValueSchema, addressChangeRequestListSchema, addressTypeSchema, agentPolicyDecisionSchema, allocateByWeight, analyticsChannelSchema, analyticsCheckoutOutcomeSchema, analyticsCheckoutSchema, analyticsDeviceRowSchema, analyticsDevicesSchema, analyticsFunnelStepSchema, analyticsOriginSchema, analyticsOverviewSchema, analyticsPagesQuerySchema, analyticsPagesSchema, analyticsProductRowSchema, analyticsProductSortSchema, analyticsProductsQuerySchema, analyticsProductsSchema, analyticsRangeQuerySchema, analyticsRealtimeSchema, analyticsSearchQuerySchema, analyticsSearchSchema, analyticsSourceGroupBySchema, analyticsSourceRowSchema, analyticsSourcesQuerySchema, analyticsSourcesSchema, analyticsTotalsSchema, apiLogErrorSchema, apiLogListQuerySchema, apiLogPageSchema, apiLogPrincipalSchema, apiLogPrincipalTypeSchema, apiLogSchema, apiLogStatusFilterSchema, apiLogSummarySchema, approvalDecisionRequestSchema, approvalListQuerySchema, approvalPageSchema, approvalRequestSchema, approvalStatusSchema, approveClaimResultSchema, auditActorSchema, auditActorTypeSchema, auditLogListQuerySchema, auditLogOutcomeSchema, auditLogPageSchema, auditLogSchema, auditLogSourceSchema, bestSellingRuleOf, buildAuthorizeUrl, buildQuery, bulkResultSchema, businessInfoPatchShape, businessInfoResponseShape, businessNumberSchema, cancelBySellerRequestSchema, cancelBySellerResultSchema, carrierSchema, cashReceiptSchema, categoryAttributeSchema, categoryCreateRequestSchema, categoryDeleteQuerySchema, categoryDeleteStrategySchema, categoryListQuerySchema, categoryPatchRequestSchema, categoryProductSortSchema, categorySchema, categorySearchResultSchema, categoryTreeNodeSchema, categoryWithPathSchema, changeStorefrontSlugRequestSchema, changeStorefrontTemplateRequestSchema, changeTypeSchema, claimDetailSchema, claimHoldResultSchema, claimListQuerySchema, claimReasonSchema, claimReturnAddressSchema, claimSchema, claimStatusSchema, claimTypeSchema, claimWebhookEventDataSchema, claimWebhookEventSchema, collectionCreateRequestSchema, collectionListQuerySchema, collectionPageSchema, collectionPatchRequestSchema, collectionPreviewRequestSchema, collectionPreviewSchema, collectionProductListQuerySchema, collectionProductSchema, collectionProductSortRequestSchema, collectionProductsAddRequestSchema, collectionProductsReplaceRequestSchema, collectionRuleCategoryIds, collectionRuleSchema, collectionRuleViewSchema, collectionRulesPredicate, collectionRulesSchema, collectionSchema, collectionStateCountsSchema, collectionStateOf, collectionStateSchema, commerceNumberField, compareBySales, consentActionSchema, consentKindSchema, consentSourceSchema, couponBenefitSchema, couponConditionsInputSchema, couponConditionsSchema, couponDiscountOf, couponIssueListQuerySchema, couponIssueMethodSchema, couponIssueSchema, couponIssueStatusSchema, couponKindSchema, couponListQuerySchema, couponRedemptionListQuerySchema, couponRedemptionSchema, couponRejectReasonSchema, couponRuleSchema, couponSchema, couponStatsSchema, couponStatusSchema, couponTargetInputSchema, couponTargetSchema, createCouponRequestSchema, createPkcePair, createStoreClient, createStoreSession, createStorefrontEditPreviewLinkRequestSchema, createStorefrontPreviewLinkRequestSchema, createStorefrontSiteRequestSchema, createStorefrontVersionRequestSchema, customInputLabelForbiddenWord, customInputRequestSchema, customInputSchema, customInputValueSchema, customerAddressSchema, customerConsentListQuerySchema, customerConsentSchema, customerConsentStateSchema, customerConsentsSchema, customerCouponSchema, customerDelegationRequestSchema, customerDelegationSchema, customerDetailSchema, customerInquiryCategorySchema, customerInquiryListQuerySchema, customerListQuerySchema, customerOrderSchema, customerPointsSchema, customerSortSchema, customerStatsSchema, customerSummarySchema, customerWithdrawalBlockedDetailsSchema, deleteStorefrontFileRequestSchema, deliveryBundleKeyOf, deliveryFeeWaiverSchema, deliveryInfoSchema, deliveryMethodSchema, deliveryStatusSchema, deliveryTypeSchema, descendantCategoryIdsOf, disableStorefrontHostingRequestSchema, discountRequestSchema, discountSchema, dispatchRequestSchema, easyPayProviderResponseSchema, easyPayProviderSchema, eventTypeSchema, exchangeAuthorizationCode, formatOrderNo, fulfillBulkRequestSchema, fulfillRequestSchema, fulfillmentRuleOf, fulfillmentTypeOf, fulfillmentTypeResponseSchema, fulfillmentTypeSchema, holdOrderItemRequestSchema, inquiryListQuerySchema, inquirySchema, inquiryWebhookEventDataSchema, inquiryWebhookEventSchema, invitationDeliveryStatusSchema, invitationListQuerySchema, invitationSchema, inviteMemberRequestSchema, isCouponTargetLine, isEditableStorefrontPath, isReservedStoreCode, isReservedStorefrontSlug, isShowcaseStorefrontSlug, isStoreScope, isWebOrigin, issueCouponRequestSchema, issueCouponResultSchema, liveGateConditionCodeSchema, liveGateConditionSchema, liveGateErrorDetailsSchema, liveGateSchema, loginProviderSchema, loginProviderStatusSchema, loginProviderTestSchema, loginSettingsSchema, maskedSecretSchema, matchesCollectionRules, mcpRuleResultSchema, mcpToolEventSchema, moveStorefrontFileRequestSchema, myAccountSchema, myStoreSchema, normalizeBusinessNumber, normalizeCouponCode, normalizeStorefrontHostname, normalizeStorefrontPath, oauthTokenResponseSchema, openFulfillmentUnion, optionGroupKindSchema, optionGroupRequestSchema, optionGroupSchema, optionModelRequestSchema, optionModelSchema, optionSelectionSchema, optionSortSchema, optionValueRequestSchema, optionValueSchema, orderCanceledWebhookEventDataSchema, orderCanceledWebhookEventSchema, orderDiscountSchema, orderFulfilledWebhookEventDataSchema, orderFulfilledWebhookEventSchema, orderItemFulfillmentSchema, orderItemFulfillmentSnapshotResponseSchema, orderItemFulfillmentSnapshotSchema, orderItemListQuerySchema, orderItemMemoResultSchema, orderItemPageSchema, orderItemSchema, orderItemStatusSchema, orderListQuerySchema, orderSchema, orderSummaryPageSchema, orderSummarySchema, orderWebhookEventDataSchema, orderWebhookEventSchema, pageInfoSchema, pageQueryShape, pageSchema, parseOrderNo, paymentAttemptRecordSchema, paymentAttemptStatusSchema, paymentCredentialSetSchema, paymentFailureWarningSchema, paymentListQuerySchema, paymentProviderSchema, paymentProviderVerificationSchema, paymentRecordDetailSchema, paymentRecordPageSchema, paymentRecordSchema, paymentRecordStatusSchema, paymentRefundRecordSchema, paymentSettingsSchema, pgEnvironmentSchema, pgPaymentMethodSchema, pgProviderSchema, pgVerificationResultSchema, planCodeSchema, planEntitlementsSchema, planErrorDetailsSchema, pointAdjustmentRequestSchema, pointAdjustmentResultSchema, pointEarnOf, pointEarnRateBpSchema, pointEarningEnabled, pointEntrySchema, pointExpiresAtOf, pointHistoryQuerySchema, pointLotSchema, pointPolicyNoticeSchema, pointPolicySchema, pointRestoreExpiresAtOf, pointUseOf, pointUsePolicySchema, policyDocumentUrlSchema, policyVersionSchema, portOneChannelSchema, portOneCredentialsInputSchema, productCreateRequestSchema, productFulfillmentCreateSchema, productFulfillmentResponseSchema, productFulfillmentSchema, productFulfillmentUpdateSchema, productImageRejection, productImageUrlSchema, productListQuerySchema, productOutOfStockWebhookEventDataSchema, productOutOfStockWebhookEventSchema, productPatchRequestSchema, productRefundPolicyOverride, productRefundPolicyPatchSchema, productReplaceRequestSchema, productSchema, productSortSchema, productStatusSchema, productSummarySchema, productVariantRequestSchema, productVariantSchema, proratedPaidRefundBase, proratedPointRefund, proratedRefundBase, publicPlanSchema, publicPlansSchema, publishStorefrontVersionRequestSchema, purchaseDecisionExtendResultSchema, purchaseDecisionRequestResultSchema, purchaseEarnPolicySchema, purchaseEarnRateOf, quoteDelivery, quotePricing, rankBestSelling, refreshUserToken, refundPolicyPatchSchema, refundPolicySchema, rejectClaimRequestSchema, remoteAreaLabelOf, remoteAreaOf, remoteAreaSchema, remoteSurchargeOf, replaceStorefrontSourceRequestSchema, requiresCollection, requiresShipping, resolvePointPolicy, resolveRefundPolicy, resolveShippingPolicy, responsePlanCodeSchema, responsePointEntryTypeSchema, reviewListQuerySchema, reviewReportResultSchema, reviewRewardPointOf, reviewRewardPolicySchema, reviewSchema, reviewSortSchema, reviewWebhookEventDataSchema, reviewWebhookEventSchema, rollbackStorefrontRequestSchema, runStorefrontCheckRequestSchema, salesReportGroupBySchema, salesReportQuerySchema, salesReportRowSchema, salesReportSchema, salesTotalsSchema, saveLoginProviderRequestSchema, savedCustomInputRequestSchema, savedCustomInputSchema, savedOptionGroupRequestSchema, savedOptionGroupSchema, savedOptionSetCompositionSchema, savedOptionSetFromProductRequestSchema, savedOptionSetFromProductResultSchema, savedOptionSetListQuerySchema, savedOptionSetRequestSchema, savedOptionSetSchema, savedOptionSetSortSchema, savedOptionValueRequestSchema, savedOptionValueSchema, scopeAccessSchema, searchStorefrontFilesRequestSchema, sellerAddressListQuerySchema, sellerAddressRequestSchema, sellerAddressSchema, sellerCustomerInquirySchema, setStorefrontVisibilityRequestSchema, settleCouponShortfall, settlementDetailQuerySchema, settlementDetailSchema, settlementListQuerySchema, settlementStatusSchema, settlementSummarySchema, settlementWithDetailsSchema, shippingAddressSchema, shippingPolicyPatchSchema, shippingPolicySchema, splitRefund, storeCodeSchema, storeMemberRoleUpdatedSchema, storeMemberSchema, storePointPolicySchema, storeRoleSchema, storeSchema, storeScopeResourceSchema, storeSubscriptionSchema, storefrontBuildDependenciesSchema, storefrontBuildListQuerySchema, storefrontBuildSchema, storefrontBuildStatusSchema, storefrontCheckSchema, storefrontCheckStatusSchema, storefrontCustomDomainStatusSchema, storefrontCustomHostnameProblem, storefrontDependencyFindingSchema, storefrontDeploymentLogSchema, storefrontDeploymentSchema, storefrontDeploymentStepSchema, storefrontDnsRecordSchema, storefrontDomainSchema, storefrontDomainTxtNameOf, storefrontEditPreviewLabelOf, storefrontEditPreviewSchema, storefrontEditSessionSchema, storefrontEditSessionStatusSchema, storefrontEditingSchema, storefrontFileConflictDetailsSchema, storefrontFileContentQuerySchema, storefrontFileContentSchema, storefrontFileDeleteResultSchema, storefrontFileEncodingSchema, storefrontFileEntrySchema, storefrontFileHashSchema, storefrontFileListQuerySchema, storefrontFileListSchema, storefrontFileMoveResultSchema, storefrontFilePathSchema, storefrontFileSearchResultSchema, storefrontFileWriteResultSchema, storefrontHostingSchema, storefrontPreviewLinkSchema, storefrontProvisioningSchema, storefrontRuleResultSchema, storefrontRuleSeveritySchema, storefrontSiteDomainSchema, storefrontSiteDomainsSchema, storefrontSiteSchema, storefrontSiteStatusSchema, storefrontSlugAvailabilityQuerySchema, storefrontSlugAvailabilitySchema, storefrontSlugSchema, storefrontSourceArchivePartSchema, storefrontSourceArchiveQuerySchema, storefrontSourceBlobsResultSchema, storefrontSourceModeSchema, storefrontSourceRefSchema, storefrontSourceReplacedSchema, storefrontSourceSchema, storefrontSuspensionSchema, storefrontTemplateSchema, storefrontVerifyReportSchema, storefrontVersionCreatedSchema, storefrontVersionSchema, storefrontVersionStatusSchema, storefrontVisibilitySchema, subscriptionLimitsSchema, subscriptionStatusSchema, subscriptionUsageSchema, tossPaymentsCredentialsInputSchema, trackingStageResponseSchema, trackingUpdateResultSchema, updateCouponRequestSchema, updateLoginProviderRequestSchema, updateLoginSettingsRequestSchema, updateMemberRoleRequestSchema, updatePaymentProviderRequestSchema, updatePaymentSettingsRequestSchema, updatePointPolicyRequestSchema, updateStoreRequestSchema, uploadExtensionOf, uploadPurposeSchema, uploadRejection, uploadRequestSchema, uploadStorefrontSourceBlobsRequestSchema, uploadTicketSchema, upsertPortOneProviderRequestSchema, upsertTossPaymentsProviderRequestSchema, variantStockRequestSchema, variantStockSchema, verifyPaymentProviderRequestSchema, webhookCreatedSchema, webhookDeliveryDetailSchema, webhookDeliveryErrorCodeSchema, webhookDeliveryListQuerySchema, webhookDeliveryResourceSchema, webhookDeliverySchema, webhookDeliveryStatusSchema, webhookEventSchema, webhookFailureReasonSchema, webhookRedeliverFailedResultSchema, webhookRequestHeaderSchema, webhookRequestSchema, webhookResourceTypeSchema, webhookSchema, webhookSecretRotatedSchema, webhookStatusSchema, webhookTestRequestSchema, webhookTestResultSchema, withdrawCustomerRequestSchema, writeDryRunResultSchema, writePreviewSchema, writeStorefrontFilesRequestSchema };

package/package.json

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

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "./schemas/auth";
 export * from "./schemas/category";
 export * from "./schemas/claim";
 export * from "./schemas/collection";
+export * from "./schemas/commerce-number";
 export * from "./schemas/common";
 export * from "./schemas/coupon";
 export * from "./schemas/customer";

package/src/schemas/claim.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { commerceNumberField } from "./commerce-number";
 import { type PageParams, pageQueryShape } from "./common";
 
 export const claimTypeSchema = z.enum(["CANCEL", "RETURN", "EXCHANGE"]);
@@ -50,6 +51,9 @@ export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
 
 export const claimSchema = z.object({
   claimId: z.string(),
+  claimNo: commerceNumberField(
+    "클레임번호(이슈 #107) — `C` + YYMMDD(KST) + 숫자 8자리. 취소·반품·교환 접수 단위 번호이고 생성 후 바뀌지 않습니다",
+  ),
   type: claimTypeSchema,
   status: claimStatusSchema,
   orderId: z.string(),

package/src/schemas/commerce-number.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+/**
+ * 국내 쇼핑몰 번호 체계(이슈 #107) — 공개 ID(`ord_…` 등)와 따로 싣는 숫자 번호의 표기·필드.
+ * 번호는 서버가 만들고 생성 후 바뀌지 않는다. 새 필드라 옛 서버 응답에는 없다 — 파싱은 null로 채운다.
+ */
+
+/**
+ * 번호 표기 — 숫자를 앞에서부터 4자리씩 하이픈으로 나눈다. 주문번호 `26100284731592` → `2610-0284-7315-92`,
+ * 상품주문번호 `2610028473159201` → `2610-0284-7315-9201`. 숫자만으로 된 값이 아니면(클레임번호 `C…`) 그대로, 없으면 빈 문자열이다.
+ * 화면 표기 전용이다 — API에 보낼 때는 원래 값을 쓴다(주문번호 조회는 하이픈도 받는다)
+ */
+export function formatOrderNo(no: string | null | undefined): string {
+  if (!no) return "";
+  if (!/^\d+$/.test(no)) return no;
+  return no.match(/.{1,4}/g)?.join("-") ?? no;
+}
+
+/** 표기 하이픈·공백을 지운 숫자 번호. 숫자가 아닌 글자가 남거나 비면 null */
+export function parseOrderNo(value: string): string | null {
+  const digits = value.replace(/[\s-]/g, "");
+  return /^\d+$/.test(digits) ? digits : null;
+}
+
+/** 응답 번호 필드 — 서버는 항상 싣고, 번호 체계 이전 행(백필 전)·옛 서버 응답은 null이다 */
+export function commerceNumberField(description: string) {
+  return z.string().nullable().optional().default(null).describe(description);
+}

package/src/schemas/order.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { commerceNumberField } from "./commerce-number";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
 import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
@@ -6,6 +7,9 @@ import { customInputValueSchema, optionSelectionSchema } from "./product";
 
 export const orderSummarySchema = z.object({
   orderId: z.string(),
+  orderNo: commerceNumberField(
+    "주문번호(이슈 #107) — 숫자 14자리(YYMMDD KST + 난수 8자리), 전역 유일, 생성 후 바뀌지 않습니다. 전화 CS·ARS용 번호이고 API 경로의 식별자는 여전히 `orderId`입니다. 화면 표기는 `formatOrderNo`(4자리 하이픈)를 쓰십시오",
+  ),
   ordererName: z.string(),
   itemCount: z.number().int(),
   totalAmount: z.number().int(),
@@ -53,6 +57,9 @@ export type OrderItemFulfillment = z.infer<typeof orderItemFulfillmentSchema>;
 
 export const orderItemSchema = z.object({
   orderItemId: z.string(),
+  orderItemNo: commerceNumberField(
+    "상품주문번호(이슈 #107) — 주문번호 + 줄 순번 2자리(01부터, 100줄부터 3자리). 부분 취소·클레임·송장의 처리 단위 번호이고 생성 후 바뀌지 않습니다",
+  ),
   orderId: z.string(),
   status: orderItemStatusSchema,
   claimStatus: z.enum(["CANCEL_REQUESTED", "RETURN_REQUESTED", "EXCHANGE_REQUESTED"]).nullable(),
@@ -151,6 +158,9 @@ export type OrderDiscount = z.infer<typeof orderDiscountSchema>;
 
 export const orderSchema = z.object({
   orderId: z.string(),
+  orderNo: commerceNumberField(
+    "주문번호(이슈 #107) — 숫자 14자리(YYMMDD KST + 난수 8자리), 전역 유일, 생성 후 바뀌지 않습니다. 전화 CS·ARS용 번호이고 API 경로의 식별자는 여전히 `orderId`입니다. 화면 표기는 `formatOrderNo`(4자리 하이픈)를 쓰십시오",
+  ),
   orderedAt: z.string(),
   orderer: z.object({
     name: z.string(),
@@ -271,11 +281,14 @@ const pageQuery = {
 
 /**
  * `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
- * `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+ * `orderNo` 없이 `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜·`orderNo` 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
  * `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
  */
 export const orderListQuerySchema = z.object({
-  orderedFrom: z.string().describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). 필수"),
+  orderedFrom: z
+    .string()
+    .optional()
+    .describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). `orderNo`가 없으면 필수"),
   orderedTo: z
     .string()
     .optional()
@@ -283,7 +296,16 @@ export const orderListQuerySchema = z.object({
   status: orderItemStatusSchema
     .optional()
     .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
-  keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+  keyword: z
+    .string()
+    .optional()
+    .describe("주문 id·주문번호(일치, 하이픈 허용)·주문자명·수령인명(포함) 검색"),
+  orderNo: z
+    .string()
+    .optional()
+    .describe(
+      "주문번호 조회(이슈 #107) — 숫자 14자리, 하이픈 허용(`2610-0284-7315-92`). 주면 기간 조건 없이 그 주문만 찾습니다. 형식이 아니면 400 `INVALID_PARAMETER`",
+    ),
   fulfillmentType: z
     .string()
     .optional()
@@ -314,7 +336,10 @@ export const orderItemListQuerySchema = z.object({
 });
 
 export interface OrderListParams extends PageParams {
-  orderedFrom: string;
+  /** 조회 시작 시각 — `orderNo`가 없으면 필수 */
+  orderedFrom?: string;
+  /** 주문번호 조회(이슈 #107) — 주면 기간 없이 그 주문만 찾는다 */
+  orderNo?: string;
   orderedTo?: string;
   status?: z.infer<typeof orderItemStatusSchema>;
   keyword?: string;

package/src/schemas/payment.ts

@@ -624,7 +624,18 @@ export const paymentRecordSchema = z.object({
   environment: pgEnvironmentSchema.nullable().describe("결제 환경"),
   testPayment: z.boolean().describe("샌드박스 결제인가"),
   pgTransactionId: z.string().nullable().describe("PG 거래 id (토스 paymentKey, 포트원 txId)"),
-  attemptId: z.string().nullable().describe("PG에 보낸 주문번호 = 시도 id"),
+  attemptId: z
+    .string()
+    .nullable()
+    .describe("대표 시도 id. 번호 체계(이슈 #107) 이전 시도는 이 값을 PG 주문번호로 보냈습니다"),
+  pgOrderId: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다",
+    ),
   attemptCount: z.number().int().describe("시도 횟수"),
   failCode: z.string().nullable().describe("실패 코드. 실패로 끝난 결제만"),
   failMessage: z.string().nullable().describe("실패 사유"),
@@ -646,6 +657,14 @@ export type PaymentRecordPage = z.infer<typeof paymentRecordPageSchema>;
 
 export const paymentAttemptRecordSchema = z.object({
   attemptId: z.string(),
+  pgOrderId: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "PG에 보낸 주문번호(이슈 #107) — 토스페이먼츠 orderId·포트원 paymentId. 새 시도는 `{주문번호}-{시도 순번 2자리}`이고, 번호 체계 이전 시도는 시도 id(`attemptId`)와 같습니다. PG 관리자 화면에서 결제를 찾을 때 씁니다",
+    ),
   sequence: z.number().int().describe("결제 건 안에서의 순번 (1부터)"),
   provider: pgProviderSchema,
   status: paymentAttemptStatusSchema,
@@ -721,7 +740,7 @@ export const paymentListQuerySchema = z.object({
   keyword: z
     .string()
     .optional()
-    .describe("결제 id·주문번호·PG 거래 id·시도 id(일치), 구매자명(포함)"),
+    .describe("결제 id·주문 id·PG 거래 id·시도 id·PG 주문번호(일치), 구매자명(포함)"),
   includeTest: z
     .string()
     .optional()

package/src/schemas/product.ts

@@ -16,6 +16,15 @@ export type ProductStatus = z.infer<typeof productStatusSchema>;
 
 export const productSummarySchema = z.object({
   productId: z.string(),
+  productNo: z
+    .number()
+    .int()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "상품번호(이슈 #107) — 상점별 1부터 증가하는 숫자, 상점 안에서 유일, 생성 후 바뀌지 않으며 지운 상품의 번호는 다시 쓰지 않습니다. URL에 써도 됩니다(스토어프론트 상품 상세 경로가 받습니다). 번호 체계 이전 응답은 null",
+    ),
   name: z.string(),
   status: productStatusSchema,
   salePrice: z.number().int().describe("판매가. 원(KRW) 단위 정수"),
@@ -72,6 +81,14 @@ export type OptionGroup = z.infer<typeof optionGroupSchema>;
  */
 export const productVariantSchema = z.object({
   variantId: z.string(),
+  variantNo: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "조합 번호(이슈 #107) — `{productNo}-{조합 순번 2자리}`(예: `10482-03`). 시스템이 매기는 SKU이고 상점 안에서 유일합니다(상품번호가 상점 범위라 다른 상점과는 겹칠 수 있습니다). 생성 후 바뀌지 않으며, 지운 조합의 번호는 다시 쓰지 않습니다. 셀러가 입력하는 `sku`와 별개입니다",
+    ),
   /** 축 sortOrder 순서와 1:1 대응. 옵션 없는 상품은 [] */
   valueIds: z.array(z.string()),
   /** 값 이름을 " / "로 이은 파생 표시명. 옵션 없으면 "" */
@@ -657,6 +674,8 @@ export interface ProductListParams extends PageParams {
   categoryId?: string;
   keyword?: string;
   sellerCode?: string;
+  /** 상품번호(이슈 #107, 상점 범위) — 그 상품만 */
+  productNo?: number;
   sort?: ProductSort;
 }
 
@@ -669,6 +688,12 @@ export const productListQuerySchema = z.object({
     .string()
     .optional()
     .describe("판매자 상품코드 — 이 코드가 붙은 variant를 가진 상품"),
+  productNo: z
+    .string()
+    .optional()
+    .describe(
+      "상품번호(이슈 #107) — 이 상점의 그 번호 상품만. 숫자가 아니면 400 `INVALID_PARAMETER`",
+    ),
   sort: productSortSchema.optional().describe("정렬 (기본 createdAt.desc)"),
   ...pageQueryShape(),
 });

package/src/schemas/promotion.ts

@@ -316,7 +316,7 @@ export interface PricingResult {
   pointAmount: number;
   /** 지금 쓸 수 있는 최대 적립금 — 주문서 안내값(잔액을 모두 요청했을 때의 금액). 적립금 입력이 없으면 0 */
   pointMaxUsable: number;
-  /** 요청보다 적게 썼다면 그 이유 — `MIN_PAYMENT`: 결제 금액 100원을 남기려고 줄였다 */
+  /** 요청보다 적게 썼다면 그 이유 — `MIN_PAYMENT`: 남는 결제 금액이 1~99원이라 100원을 남기려고 줄였다(전액이면 0원 결제) */
   pointAdjustReason: "MIN_PAYMENT" | null;
   /** 요청했지만 쓰지 못했다면 그 이유 */
   pointRejectReason: PointRejectReason | null;
@@ -662,8 +662,10 @@ export function quotePricing(input: PricingInput): PricingResult {
 }
 
 /**
- * 사용 적립금 금액(순수) — 요청·잔액·최대 비율·「결제 금액 100원 남기기」 중 작은 값을 단위로 내린다.
- * 최소 보유액·최소 사용액에 못 미치면 0이다. 결제 금액이 0원이 되는 사용(적립금 전액 결제)은 아직 받지 않는다(P4).
+ * 사용 적립금 금액(순수) — 요청·잔액·최대 비율 중 작은 값을 쓴다(#93 P3·P4).
+ * - 결제 금액 전체를 덮을 수 있으면 전액을 쓴다(0원 결제, 이때만 사용 단위를 보지 않는다)
+ * - 그 밖에는 사용 단위로 내리고, 남는 결제 금액이 1~99원이면 적립금을 줄여 100원을 남긴다(`MIN_PAYMENT`)
+ * 최소 보유액·최소 사용액에 못 미치면 0이다.
  */
 export function pointUseOf(
   points: PricingPoints | null,
@@ -680,27 +682,38 @@ export function pointUseOf(
   const unit = Math.max(1, Math.floor(rules.unit));
   const base = amounts.productPaid + (rules.includeDeliveryFee ? amounts.deliveryPaid : 0);
   const byRatio = Math.floor((base * rules.maxRatioBp) / 10_000);
-  // 결제 금액은 0원 또는 100원 이상이어야 하고, 지금은 0원 결제를 받지 않으므로 100원을 남긴다
-  const byPayment = Math.max(0, amounts.total - MIN_PAYMENT_AMOUNT);
   const balance = Math.max(0, points.balance);
+  const total = Math.max(0, amounts.total);
   const floorUnit = (value: number) => Math.floor(Math.max(0, value) / unit) * unit;
+  /** 상한 `cap`으로 쓸 수 있는 금액 — 전액이면 0원 결제, 아니면 단위 내림 + 100원 남기기 */
+  const usableWithin = (cap: number): { amount: number; adjusted: boolean } => {
+    if (total > 0 && cap >= total) return { amount: total, adjusted: false };
+    const amount = floorUnit(Math.min(cap, total));
+    const remaining = total - amount;
+    if (remaining > 0 && remaining < MIN_PAYMENT_AMOUNT) {
+      return { amount: floorUnit(total - MIN_PAYMENT_AMOUNT), adjusted: true };
+    }
+    return { amount, adjusted: false };
+  };
   const eligible = balance >= rules.minBalance;
-  const ceiling = Math.min(balance, byRatio, byPayment);
-  const maxUsable = eligible && floorUnit(ceiling) >= rules.minAmount ? floorUnit(ceiling) : 0;
+  const ceiling = usableWithin(Math.min(balance, byRatio)).amount;
+  const maxUsable = eligible && ceiling > 0 && ceiling >= rules.minAmount ? ceiling : 0;
   const requested = Math.max(0, Math.floor(points.requested));
   if (requested === 0) return { ...none, maxUsable };
   if (!eligible) return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_BALANCE" };
-  const amount = floorUnit(Math.min(requested, balance, byRatio, byPayment));
-  if (amount <= 0) {
+  const used = usableWithin(Math.min(requested, balance, byRatio));
+  if (used.amount <= 0) {
     return { amount: 0, maxUsable, adjustReason: null, rejectReason: "NOT_PAYABLE" };
   }
-  if (amount < rules.minAmount) {
+  if (used.amount < rules.minAmount) {
     return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_AMOUNT" };
   }
-  // 요청이 결제 금액 100원 남기기에 걸려 줄었다
-  const adjustReason =
-    floorUnit(Math.min(requested, balance, byRatio)) > amount ? "MIN_PAYMENT" : null;
-  return { amount, maxUsable, adjustReason, rejectReason: null };
+  return {
+    amount: used.amount,
+    maxUsable,
+    adjustReason: used.adjusted ? "MIN_PAYMENT" : null,
+    rejectReason: null,
+  };
 }
 
 // ─── 환불 정산: 조건 미달 차감 ─────────────────────────────