@sayren/store-sdk 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -1082,6 +1082,22 @@ export declare const claimReasonSchema: z.ZodEnum<{
   DELAY: "DELAY";
 }>;
 export type ClaimReason = z.infer<typeof claimReasonSchema>;
+/**
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 상품이 반품지를 따로 지정했으면 그 주소다.
+ *
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+ */
+export declare const claimReturnAddressSchema: z.ZodObject<{
+  name: z.ZodString;
+  contactName: z.ZodString;
+  phone: z.ZodString;
+  zipCode: z.ZodString;
+  address1: z.ZodString;
+  address2: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
 export declare const claimSchema: z.ZodObject<{
   claimId: z.ZodString;
   type: z.ZodEnum<{
@@ -1136,6 +1152,14 @@ export declare const claimSchema: z.ZodObject<{
   completedAt: z.ZodNullable<z.ZodString>;
   holdExpiresAt: z.ZodNullable<z.ZodString>;
   holdUsed: z.ZodBoolean;
+  returnAddress: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    contactName: z.ZodString;
+    phone: z.ZodString;
+    zipCode: z.ZodString;
+    address1: z.ZodString;
+    address2: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Claim = z.infer<typeof claimSchema>;
 export interface ClaimListParams extends PageParams {
@@ -1215,6 +1239,14 @@ export declare const claimDetailSchema: z.ZodObject<{
   completedAt: z.ZodNullable<z.ZodString>;
   holdExpiresAt: z.ZodNullable<z.ZodString>;
   holdUsed: z.ZodBoolean;
+  returnAddress: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    contactName: z.ZodString;
+    phone: z.ZodString;
+    zipCode: z.ZodString;
+    address1: z.ZodString;
+    address2: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
   histories: z.ZodOptional<z.ZodArray<z.ZodObject<{
     status: z.ZodEnum<{
       REQUESTED: "REQUESTED";
@@ -2218,6 +2250,28 @@ export declare const orderSchema: z.ZodObject<{
     discountAmount: z.ZodNumber;
     totalAmount: z.ZodNumber;
     paidAt: z.ZodNullable<z.ZodString>;
+    cashReceipt: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      cashReceiptId: z.ZodString;
+      status: z.ZodString;
+      type: z.ZodString;
+      identityType: z.ZodString;
+      identityNumberMasked: z.ZodString;
+      amount: z.ZodNumber;
+      issuedAmount: z.ZodNumber;
+      provider: z.ZodNullable<z.ZodEnum<{
+        tosspayments: "tosspayments";
+        portone: "portone";
+      }>>;
+      issueNumber: z.ZodNullable<z.ZodString>;
+      receiptUrl: z.ZodNullable<z.ZodString>;
+      issuedAt: z.ZodNullable<z.ZodString>;
+      canceledAt: z.ZodNullable<z.ZodString>;
+      failCode: z.ZodNullable<z.ZodString>;
+      failMessage: z.ZodNullable<z.ZodString>;
+      reissuable: z.ZodBoolean;
+      requestedAt: z.ZodString;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>>>>;
   }, z.core.$strip>;
   testPayment: z.ZodBoolean;
   items: z.ZodArray<z.ZodObject<{
@@ -2441,7 +2495,7 @@ export declare const dispatchRequestSchema: z.ZodObject<{
   }>;
   carrierCode: z.ZodOptional<z.ZodString>;
   trackingNumber: z.ZodOptional<z.ZodString>;
-  dispatchedAt: z.ZodOptional<z.ZodString>;
+  dispatchedAt: z.ZodOptional<z.ZodISODateTime>;
 }, z.core.$strip>;
 export type DispatchRequest = z.infer<typeof dispatchRequestSchema>;
 export declare const deliveryInfoSchema: z.ZodObject<{
@@ -2465,6 +2519,11 @@ export declare const deliveryInfoSchema: z.ZodObject<{
   deliveredAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
+/**
+ * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+ * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+ */
+export declare const trackingStageResponseSchema: z.ZodString;
 /** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
 export declare const deliveryStatusSchema: z.ZodObject<{
   orderItemId: z.ZodString;
@@ -2489,7 +2548,14 @@ export declare const deliveryStatusSchema: z.ZodObject<{
     status: z.ZodString;
     location: z.ZodString;
     occurredAt: z.ZodString;
+    stage: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   }, z.core.$strip>>>;
+  tracking: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    result: z.ZodNullable<z.ZodString>;
+    stage: z.ZodNullable<z.ZodString>;
+    checkedAt: z.ZodNullable<z.ZodString>;
+    carrierDeliveredAt: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;
 /** `PUT /v1/order-items/{orderItemId}/dispatch/tracking` 응답 — 바뀐 송장 */
@@ -3268,6 +3334,40 @@ export declare const paymentRecordStatusSchema: z.ZodEnum<{
 }>;
 export type PaymentRecordStatus = z.infer<typeof paymentRecordStatusSchema>;
 export declare const paymentAttemptStatusSchema: z.ZodString;
+/**
+ * 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
+ * - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
+ * - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
+ * - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
+ * - `CANCELED`: 전액 환불로 취소됐다
+ * - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
+ * - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
+ */
+export declare const CASH_RECEIPT_STATUS_VALUES: readonly ["REQUESTED", "PENDING", "ISSUED", "CANCELED", "FAILED", "SKIPPED"];
+export type KnownCashReceiptStatus = (typeof CASH_RECEIPT_STATUS_VALUES)[number];
+export declare const cashReceiptSchema: z.ZodObject<{
+  cashReceiptId: z.ZodString;
+  status: z.ZodString;
+  type: z.ZodString;
+  identityType: z.ZodString;
+  identityNumberMasked: z.ZodString;
+  amount: z.ZodNumber;
+  issuedAmount: z.ZodNumber;
+  provider: z.ZodNullable<z.ZodEnum<{
+    tosspayments: "tosspayments";
+    portone: "portone";
+  }>>;
+  issueNumber: z.ZodNullable<z.ZodString>;
+  receiptUrl: z.ZodNullable<z.ZodString>;
+  issuedAt: z.ZodNullable<z.ZodString>;
+  canceledAt: z.ZodNullable<z.ZodString>;
+  failCode: z.ZodNullable<z.ZodString>;
+  failMessage: z.ZodNullable<z.ZodString>;
+  reissuable: z.ZodBoolean;
+  requestedAt: z.ZodString;
+  updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type CashReceipt = z.infer<typeof cashReceiptSchema>;
 export declare const paymentRecordSchema: z.ZodObject<{
   paymentId: z.ZodString;
   orderId: z.ZodNullable<z.ZodString>;
@@ -3306,6 +3406,7 @@ export declare const paymentRecordSchema: z.ZodObject<{
   failMessage: z.ZodNullable<z.ZodString>;
   paidAt: z.ZodNullable<z.ZodString>;
   createdAt: z.ZodString;
+  cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
 }, z.core.$strip>;
 export type PaymentRecord = z.infer<typeof paymentRecordSchema>;
 export declare const paymentRecordPageSchema: z.ZodObject<{
@@ -3351,6 +3452,7 @@ export declare const paymentRecordPageSchema: z.ZodObject<{
     failMessage: z.ZodNullable<z.ZodString>;
     paidAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
+    cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PaymentRecordPage = z.infer<typeof paymentRecordPageSchema>;
@@ -3439,6 +3541,7 @@ export declare const paymentRecordDetailSchema: z.ZodObject<{
   failMessage: z.ZodNullable<z.ZodString>;
   paidAt: z.ZodNullable<z.ZodString>;
   createdAt: z.ZodString;
+  cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   refundableAmount: z.ZodNumber;
   merchantId: z.ZodNullable<z.ZodString>;
   attempts: z.ZodArray<z.ZodObject<{
@@ -3486,6 +3589,28 @@ export declare const paymentRecordDetailSchema: z.ZodObject<{
     requestedAt: z.ZodString;
     completedAt: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>>;
+  cashReceipt: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    cashReceiptId: z.ZodString;
+    status: z.ZodString;
+    type: z.ZodString;
+    identityType: z.ZodString;
+    identityNumberMasked: z.ZodString;
+    amount: z.ZodNumber;
+    issuedAmount: z.ZodNumber;
+    provider: z.ZodNullable<z.ZodEnum<{
+      tosspayments: "tosspayments";
+      portone: "portone";
+    }>>;
+    issueNumber: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodNullable<z.ZodString>;
+    issuedAt: z.ZodNullable<z.ZodString>;
+    canceledAt: z.ZodNullable<z.ZodString>;
+    failCode: z.ZodNullable<z.ZodString>;
+    failMessage: z.ZodNullable<z.ZodString>;
+    reissuable: z.ZodBoolean;
+    requestedAt: z.ZodString;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type PaymentRecordDetail = z.infer<typeof paymentRecordDetailSchema>;
 /** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
@@ -3795,7 +3920,7 @@ export declare const productCreateRequestSchema: z.ZodObject<{
     PAID: "PAID";
     CONDITIONAL_FREE: "CONDITIONAL_FREE";
   }>>;
-  deliveryFee: z.ZodDefault<z.ZodNumber>;
+  deliveryFee: z.ZodOptional<z.ZodNumber>;
   conditionalFreeAmount: z.ZodOptional<z.ZodNumber>;
   returnFee: z.ZodDefault<z.ZodNumber>;
   exchangeFee: z.ZodDefault<z.ZodNumber>;
@@ -3806,8 +3931,8 @@ export declare const productCreateRequestSchema: z.ZodObject<{
     sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
     conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strict>>>;
-  shippingAddressId: z.ZodOptional<z.ZodString>;
-  returnAddressId: z.ZodOptional<z.ZodString>;
+  shippingAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  returnAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   optionGroups: z.ZodDefault<z.ZodArray<z.ZodObject<{
     groupId: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
@@ -3840,6 +3965,8 @@ export declare const productPatchRequestSchema: z.ZodObject<{
     CLOSED: "CLOSED";
   }>>;
   deliveryFee: z.ZodOptional<z.ZodNumber>;
+  shippingAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  returnAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type ProductPatchRequest = z.infer<typeof productPatchRequestSchema>;
 export declare const productSortSchema: z.ZodEnum<{
@@ -3950,6 +4077,12 @@ export declare const updateStoreRequestSchema: z.ZodObject<{
     sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
     conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
   }, z.core.$strict>>;
+  shippingPolicy: z.ZodOptional<z.ZodObject<{
+    baseDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    freeThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    jejuSurcharge: z.ZodOptional<z.ZodNumber>;
+    isolatedSurcharge: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
   termsVersion: z.ZodOptional<z.ZodString>;
   privacyVersion: z.ZodOptional<z.ZodString>;
   termsUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
@@ -3981,6 +4114,12 @@ export declare const storeSchema: z.ZodObject<{
     sellerFaultFreeShipping: z.ZodBoolean;
     conditionalFreeShortfallCharge: z.ZodBoolean;
   }, z.core.$strip>;
+  shippingPolicy: z.ZodObject<{
+    baseDeliveryFee: z.ZodNumber;
+    freeThreshold: z.ZodNullable<z.ZodNumber>;
+    jejuSurcharge: z.ZodNumber;
+    isolatedSurcharge: z.ZodNumber;
+  }, z.core.$strip>;
   termsVersion: z.ZodString;
   privacyVersion: z.ZodString;
   termsVersionUpdatedAt: z.ZodNullable<z.ZodString>;
@@ -4911,6 +5050,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
         discountAmount: number;
         totalAmount: number;
         paidAt: string | null;
+        cashReceipt: {
+          cashReceiptId: string;
+          status: string;
+          type: string;
+          identityType: string;
+          identityNumberMasked: string;
+          amount: number;
+          issuedAmount: number;
+          provider: "tosspayments" | "portone" | null;
+          issueNumber: string | null;
+          receiptUrl: string | null;
+          issuedAt: string | null;
+          canceledAt: string | null;
+          failCode: string | null;
+          failMessage: string | null;
+          reissuable: boolean;
+          requestedAt: string;
+          updatedAt: string;
+        } | null;
       };
       testPayment: boolean;
       items: {
@@ -4941,6 +5099,29 @@ export declare function createStoreClient(options: StoreClientOptions): {
         testPayment: boolean;
       }[];
     }>;
+    /**
+     * `POST /v1/orders/{orderId}/cash-receipt/reissue` — 실패했거나 재시도 대기 중인 현금영수증을 지금 다시 발급·취소한다.
+     * 콘솔 OWNER·ADMIN 전용(PAT·M2M 403 `INSUFFICIENT_ROLE`). 404 `CASH_RECEIPT_NOT_FOUND`, 409 `CASH_RECEIPT_NOT_REISSUABLE`
+     */
+    reissueCashReceipt: (orderId: string) => Promise<{
+      cashReceiptId: string;
+      status: string;
+      type: string;
+      identityType: string;
+      identityNumberMasked: string;
+      amount: number;
+      issuedAmount: number;
+      provider: "tosspayments" | "portone" | null;
+      issueNumber: string | null;
+      receiptUrl: string | null;
+      issuedAt: string | null;
+      canceledAt: string | null;
+      failCode: string | null;
+      failMessage: string | null;
+      reissuable: boolean;
+      requestedAt: string;
+      updatedAt: string;
+    }>;
   };
   orderItems: {
     /** `GET /v1/order-items`. `testPayment` 필터는 `orders.list`와 같다 */
@@ -5082,10 +5263,17 @@ export declare function createStoreClient(options: StoreClientOptions): {
       status: "DISPATCHED" | "DELIVERING" | "DELIVERED";
       dispatchedAt: string;
       deliveredAt: string | null;
+      tracking: {
+        result: string | null;
+        stage: string | null;
+        checkedAt: string | null;
+        carrierDeliveredAt: string | null;
+      } | null;
       trackingEvents?: {
         status: string;
         location: string;
         occurredAt: string;
+        stage: string | null;
       }[] | undefined;
     }>;
   };
@@ -5129,6 +5317,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
         completedAt: string | null;
         holdExpiresAt: string | null;
         holdUsed: boolean;
+        returnAddress: {
+          name: string;
+          contactName: string;
+          phone: string;
+          zipCode: string;
+          address1: string;
+          address2: string | null;
+        } | null;
       }[];
     }>;
     get: (claimId: string) => Promise<{
@@ -5158,6 +5354,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
       completedAt: string | null;
       holdExpiresAt: string | null;
       holdUsed: boolean;
+      returnAddress: {
+        name: string;
+        contactName: string;
+        phone: string;
+        zipCode: string;
+        address1: string;
+        address2: string | null;
+      } | null;
       histories?: {
         status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
         actor: "BUYER" | "SELLER" | "SYSTEM";
@@ -5213,6 +5417,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
       completedAt: string | null;
       holdExpiresAt: string | null;
       holdUsed: boolean;
+      returnAddress: {
+        name: string;
+        contactName: string;
+        phone: string;
+        zipCode: string;
+        address1: string;
+        address2: string | null;
+      } | null;
     }>;
   };
   inquiries: {
@@ -5846,6 +6058,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         failMessage: string | null;
         paidAt: string | null;
         createdAt: string;
+        cashReceiptStatus: string | null;
       }[];
     }>;
     /** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
@@ -5869,6 +6082,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       failMessage: string | null;
       paidAt: string | null;
       createdAt: string;
+      cashReceiptStatus: string | null;
       refundableAmount: number;
       merchantId: string | null;
       attempts: {
@@ -5898,6 +6112,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
         requestedAt: string;
         completedAt: string | null;
       }[];
+      cashReceipt: {
+        cashReceiptId: string;
+        status: string;
+        type: string;
+        identityType: string;
+        identityNumberMasked: string;
+        amount: number;
+        issuedAmount: number;
+        provider: "tosspayments" | "portone" | null;
+        issueNumber: string | null;
+        receiptUrl: string | null;
+        issuedAt: string | null;
+        canceledAt: string | null;
+        failCode: string | null;
+        failMessage: string | null;
+        reissuable: boolean;
+        requestedAt: string;
+        updatedAt: string;
+      } | null;
     }>;
   };
   /**
@@ -6857,6 +7090,12 @@ export declare function createStoreClient(options: StoreClientOptions): {
         sellerFaultFreeShipping: boolean;
         conditionalFreeShortfallCharge: boolean;
       };
+      shippingPolicy: {
+        baseDeliveryFee: number;
+        freeThreshold: number | null;
+        jejuSurcharge: number;
+        isolatedSurcharge: number;
+      };
       termsVersion: string;
       privacyVersion: string;
       termsVersionUpdatedAt: string | null;
@@ -6891,6 +7130,12 @@ export declare function createStoreClient(options: StoreClientOptions): {
         sellerFaultFreeShipping: boolean;
         conditionalFreeShortfallCharge: boolean;
       };
+      shippingPolicy: {
+        baseDeliveryFee: number;
+        freeThreshold: number | null;
+        jejuSurcharge: number;
+        isolatedSurcharge: number;
+      };
       termsVersion: string;
       privacyVersion: string;
       termsVersionUpdatedAt: string | null;
@@ -7107,6 +7352,194 @@ export declare const STORE_ROLE_SCOPES: {
   readonly STAFF: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "customer:r"];
 };
 //#endregion
+//#region src/schemas/shipping-policy.d.ts
+/** 유효 배송비 정책 — 스토어가 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
+export declare const shippingPolicySchema: z.ZodObject<{
+  baseDeliveryFee: z.ZodNumber;
+  freeThreshold: z.ZodNullable<z.ZodNumber>;
+  jejuSurcharge: z.ZodNumber;
+  isolatedSurcharge: z.ZodNumber;
+}, z.core.$strip>;
+export type ShippingPolicy = z.infer<typeof shippingPolicySchema>;
+/**
+ * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ *
+ * `as const`가 아니라 `ShippingPolicy`로 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
+ * `null` 자리에 숫자를 넣을 수 없다(`REFUND_POLICY_DEFAULTS`와 같은 이유).
+ */
+export declare const SHIPPING_POLICY_DEFAULTS: ShippingPolicy;
+/**
+ * 부분 정책 — `PATCH /v1/store`의 `shippingPolicy`가 쓴다. 준 항목만 바뀐다.
+ *
+ * `strictObject`라 모르는 키는 400이다. 오타를 조용히 무시하면 셀러는 저장됐다고 믿는데
+ * 정책은 기본값으로 남는다(`refundPolicyPatchSchema`와 같은 이유).
+ */
+export declare const shippingPolicyPatchSchema: z.ZodObject<{
+  baseDeliveryFee: z.ZodOptional<z.ZodNumber>;
+  freeThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  jejuSurcharge: z.ZodOptional<z.ZodNumber>;
+  isolatedSurcharge: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ShippingPolicyPatch = z.infer<typeof shippingPolicyPatchSchema>;
+/** 유효 정책 해석 — 스토어가 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
+export declare function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy;
+/** 지역 구분 — 우편번호로 판정한다 */
+export declare const remoteAreaSchema: z.ZodEnum<{
+  NONE: "NONE";
+  JEJU: "JEJU";
+  ISOLATED: "ISOLATED";
+}>;
+export type RemoteArea = z.infer<typeof remoteAreaSchema>;
+/**
+ * 제주·도서산간 우편번호 범위 — **코드 상수다.** 금액은 스토어가 정하고 범위는 플랫폼이 고정한다.
+ *
+ * 국내 택배사가 공표하는 제주·도서산간 할증 구간을 5자리 우편번호 범위로 옮긴 표다. 셀러마다
+ * 범위가 다르면 같은 주소에 다른 금액이 나가고 CS가 셀러 수만큼 갈라진다. 스토어별 범위 편집은
+ * 후속 과제이고, 지금은 이 표가 유일한 원천이다.
+ *
+ * ## 근거
+ *
+ * 원천은 **CJ대한통운이 공표한 「제주 및 도서산간 지역 추가 운송비」 표**(구간 시작·끝 우편번호와
+ * 지역명이 붙은 그 표)다. 같은 표가 한진택배 공지와 쇼핑몰 솔루션 안내에도 같은 값으로 실린다.
+ * 서로 다른 게시자의 전재본 네 곳이 인천·전남·경남 구간까지 글자 그대로 일치하는 것을 확인했다.
+ *
+ * - CJ대한통운 표 전재 (구간별 금액 포함): https://ichibanhouse.com/article/공지뉴스/1/16/
+ * - 같은 표의 다른 전재본: https://peppytail.com/article/공지사항/1/4046/
+ * - 시행 시점(2020-02-01)과 구간별 행정구역명을 함께 적은 전재본:
+ *   https://tosstoss.co.kr/bbs/content.php?co_id=pilotage
+ * - 솔루션 안내 「제주도 및 도서산간 지역 기준표」:
+ *   https://help.campaignus.me/ko/articles/제주도-및-도서산간-지역-기준표-342d2e5e
+ *
+ * 라벨의 행정구역명은 우편번호 배정을 따로 확인해 고쳤다. 택배사 표의 지역명은 축약·오기가 있다.
+ * 확인한 것만 남기고, 확인하지 못한 구간은 이 표에서 뺀다 — 판정하지 못하면 받지 않는 쪽이
+ * `remoteAreaOf`의 규칙과 같다.
+ *
+ * ## 표에서 뺀 구간
+ *
+ * - **54000**: 택배사 표는 「경남 통영 섬지역3」으로 적었지만 이 번호는 **전북 군산시 옥도면**이다.
+ *   게다가 공정거래위원회가 2025-10-07 발표에서 연륙교로 이어진 신시도·야미도·선유도와 비연륙
+ *   도서(방축도·관리도)가 같은 우편번호를 쓰는 대표 사례로 이 지역을 들었다. 라벨도 부과 근거도
+ *   확정하지 못해 뺀다.
+ * - **강화군 본섬(23000~23003, 23011~23099)**: 택배사 표의 강화 할증 구간은 23004~23010
+ *   (교동면·삼산면·서도면)뿐이다. 강화대교·초지대교로 이어진 본섬은 도선료가 없어 어느 택배사도
+ *   할증하지 않는다. 「누락」이 아니라 대상이 아니다.
+ *
+ * ## 한계
+ *
+ * 우편번호 단위 판정은 한 번호 안에 연륙도서와 비연륙도서가 섞인 구간에서 과대 부과가 된다.
+ * 공정위가 2025-10-07에 온라인몰 13곳의 이 방식을 시정하게 한 지적이 그것이다
+ * (https://eiec.kdi.re.kr/policy/materialView.do?num=272070). 아래 구간 중 33411(보령 오천면,
+ * 원산도가 해저터널로 연결), 46768~46771(강서구 가덕도, 거가대교로 연결)이 그런 혼재 구간이다.
+ * 도로명주소·건물관리번호 단위 판정은 후속 과제다.
+ *
+ * 범위는 **닫힌 구간**(`from` ≤ zip ≤ `to`)이고 겹치지 않는다. 앞에서부터 처음 맞는 항목을 쓴다.
+ * 순서는 콘솔 「추가 배송비 지역」 표의 행 순서이기도 하다(`remoteAreaGroups`). 제주를 먼저 두고
+ * 도서산간은 우편번호 오름차순으로 둔다.
+ */
+export declare const REMOTE_AREA_ZIP_RANGES: ReadonlyArray<{
+  readonly area: Exclude<RemoteArea, "NONE">;
+  readonly from: number;
+  readonly to: number;
+  readonly label: string;
+}>;
+/**
+ * 우편번호 → 지역 구분. 5자리 숫자가 아니면 `NONE`이다.
+ *
+ * 형식 검증은 배송지 스키마(`/^[0-9]{5}$/`)가 하고, 여기서는 **판정하지 못하면 추가 배송비를 받지 않는다**.
+ * 반대로 두면 우편번호를 잘못 넣은 주문에 근거 없는 금액이 붙는다.
+ */
+export declare function remoteAreaOf(zipCode: string | null | undefined): RemoteArea;
+/** 지역 구분의 안내 이름 — 판정된 범위의 `label`이다. 판정되지 않으면 null */
+export declare function remoteAreaLabelOf(zipCode: string | null | undefined): string | null;
+/** 묶음 하나에 붙는 지역 추가 배송비 */
+export declare function remoteSurchargeOf(policy: ShippingPolicy, area: RemoteArea): number;
+/** 묶음 판정에 쓰는 상품 값 — 출고지와 배송 정책이다 */
+export interface DeliveryBundleProduct {
+  deliveryType: DeliveryType;
+  deliveryFee: number;
+  conditionalFreeAmount: number | null;
+  /** 출고지 주소 id(`seller_addresses`). null이면 스토어 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
+  shippingAddressId?: string | null;
+}
+/**
+ * 배송 묶음 키 — **같은 출고지 + 같은 배송 정책이면 같은 키다.**
+ *
+ * 키는 주문 시점에 주문상품 행에 스냅샷된다(`order_items.delivery_bundle_key`). 셀러가 주문 뒤
+ * 출고지나 배송비를 바꿔도 그 주문의 묶음은 움직이지 않는다 — 움직이면 이미 환불한 묶음의 키가
+ * 달라져 `orders.delivery_fee_settlements`의 이중 환불 방지 표시가 무력해진다.
+ *
+ * `-`는 「값 없음」이다. 사람이 읽을 수 있게 남기고, 값 자체에 `:`가 들어갈 수 없는 형식만 쓴다
+ * (주소 id는 `adr_…`, 나머지는 열거형·정수).
+ */
+export declare function deliveryBundleKeyOf(product: DeliveryBundleProduct): string;
+/** 계산에 넣는 한 줄 — 주문상품·장바구니 항목·주문서 항목이 이 형태로 들어온다 */
+export interface DeliveryFeeLine {
+  productId: string;
+  /** 상품 금액 (할인 반영 단가 × 수량) */
+  amount: number;
+}
+/**
+ * 기본 배송비를 면제한 근거 — 면제하지 않았으면 null이다.
+ *
+ * 환불 정산이 근거를 구분해야 한다. 조건부 무료 기준 미달 차감은 **상품별 조건부 무료(`CONDITIONAL`)로
+ * 면제된 묶음만** 대상이다. 스토어 전체 무료 기준(`STORE_THRESHOLD`)이나 무료배송 상품(`FREE`)은 셀러가
+ * 배송비를 받지 않기로 한 것이므로, 일부 취소로 기준이 깨져도 구매자에게 배송비를 물리지 않는다.
+ *
+ * 세 값이 겹치면 `FREE` → `STORE_THRESHOLD` → `CONDITIONAL` 순으로 센 근거를 남긴다.
+ */
+export declare const deliveryFeeWaiverSchema: z.ZodEnum<{
+  FREE: "FREE";
+  STORE_THRESHOLD: "STORE_THRESHOLD";
+  CONDITIONAL: "CONDITIONAL";
+}>;
+export type DeliveryFeeWaiver = z.infer<typeof deliveryFeeWaiverSchema>;
+/** 묶음 하나의 견적 */
+export interface DeliveryBundleQuote {
+  bundleKey: string;
+  /** 이 묶음에 든 상품 id — 스냅샷 검증과 콘솔 안내에 쓴다 */
+  productIds: string[];
+  /** 실제 청구한 기본 배송비 — 무료배송·무료 기준 충족이면 0 */
+  fee: number;
+  /** 기본 배송비를 면제한 근거. 청구했으면 null */
+  waivedBy: DeliveryFeeWaiver | null;
+  /** 배송비 정가 — 조건부 무료 미달 차감액의 상한이다 */
+  listFee: number;
+  /** 묶음 조건부 무료 기준액. 조건부 무료가 아니면 null */
+  freeThreshold: number | null;
+  /** 이 묶음에 붙은 지역 추가 배송비 */
+  remoteSurcharge: number;
+}
+/** 배송비 견적 — 합계와 묶음 내역 */
+export interface DeliveryQuote {
+  bundles: DeliveryBundleQuote[];
+  /** 기본 배송비 합계 (지역 추가 제외) */
+  baseFee: number;
+  /** 지역 추가 배송비 합계 */
+  remoteSurcharge: number;
+  /** 청구할 배송비 총액 = `baseFee` + `remoteSurcharge` */
+  deliveryFee: number;
+  remoteArea: RemoteArea;
+  /** 스토어 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
+  freeByThreshold: boolean;
+}
+export interface DeliveryQuoteInput {
+  lines: DeliveryFeeLine[];
+  /** 상품 배송 정책 조회 — 못 읽은 상품은 계산에서 빠진다(배송비를 만들어 붙이지 않는다) */
+  productOf: (productId: string) => DeliveryBundleProduct | undefined;
+  policy: ShippingPolicy;
+  /** 배송지 우편번호. 아직 모르면 생략한다 — 지역 추가 배송비 0으로 계산한다 */
+  zipCode?: string | null;
+}
+/**
+ * 배송비 계산 — **순수 함수다.** 장바구니 요약, 주문서 금액, 결제 시작의 최종 확정,
+ * 주문 배송비 스냅샷이 모두 이 한 곳을 쓴다.
+ *
+ * 순서가 규칙이다. 묶음별 조건부 무료를 먼저 보고, 그다음 스토어 전체 무료 기준으로 기본 배송비를
+ * 한꺼번에 0으로 만들고, 마지막에 지역 추가 배송비를 묶음마다 더한다. 추가 배송비는 무료 기준에
+ * 걸리지 않는다.
+ */
+export declare function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote;
+//#endregion
 //#region src/schemas/webhook-event.d.ts
 export declare const orderWebhookEventDataSchema: z.ZodObject<{
   orderId: z.ZodString;