@sayren/storefront-sdk 0.10.0 → 0.11.1

package/src/client.ts

@@ -37,6 +37,9 @@ import {
   type CreateCheckoutRequest,
   checkoutSessionSchema,
   createCheckoutRequestSchema,
+  type DeliveryQuoteRequest,
+  deliveryQuoteRequestSchema,
+  deliveryQuoteSchema,
   paymentStartSchema,
   paymentStatusSchema,
   type RetryPaymentRequest,
@@ -276,6 +279,19 @@ export function createStorefrontClient(options: StorefrontClientOptions) {
         http.request("POST", "/checkout", checkoutSessionSchema, {
           body: createCheckoutRequestSchema.parse(body),
         }),
+      /**
+       * `POST /checkout/{checkoutId}/delivery-quote` — 배송비 미리보기. 배송지 우편번호로 배송비를 다시 계산한다.
+       *
+       * 주문서를 만들 때는 배송지를 모르므로 제주·도서산간 추가 배송비가 빠져 있다. 구매자가 배송지를 입력하거나
+       * 고칠 때 이 메서드로 금액을 갱신하면 결제 직전에 금액이 바뀌는 일을 피할 수 있다. 주문서를 바꾸지 않는
+       * 읽기 계산이고, **최종 금액은 결제 시작 응답의 `amounts`다.**
+       *
+       * 에러(`ApiError.code`): 404 `CHECKOUT_NOT_FOUND`, 409 `CHECKOUT_EXPIRED`, 409 `ALREADY_PAID`
+       */
+      quoteDelivery: (checkoutId: string, body: DeliveryQuoteRequest) =>
+        http.request("POST", path`/checkout/${checkoutId}/delivery-quote`, deliveryQuoteSchema, {
+          body: deliveryQuoteRequestSchema.parse(body),
+        }),
       /**
        * `POST /checkout/{checkoutId}/payment` — 결제 시작. 배송지와 결제 옵션(`paymentOptions` 항목 또는 직접 쓴 옵션)으로
        * 결제 세션·첫 시도를 만들고 결제 서비스 주소(`payUrl`)를 돌려준다. 그 주소를 열어 결제를 진행하는 것은

package/src/payments/index.ts

@@ -1,5 +1,6 @@
 import type { createStorefrontClient } from "../client";
 import {
+  type CashReceiptRequest,
   type GuestInfo,
   type PaymentOption,
   type PaymentStart,
@@ -167,7 +168,7 @@ export function paymentResultOf(
       status: "CANCELED",
       paymentId,
       code: lastFailure?.code ?? "USER_CANCELED",
-      message: lastFailure?.message ?? "결제를 취소했어요",
+      message: lastFailure?.message ?? "결제를 취소했습니다",
     };
   }
   if (result === "FAILED" || result === "EXPIRED") {
@@ -177,13 +178,13 @@ export function paymentResultOf(
       code: lastFailure?.code ?? result,
       message:
         lastFailure?.message ??
-        (result === "EXPIRED" ? "결제 요청이 만료됐어요" : "결제에 실패했어요"),
+        (result === "EXPIRED" ? "결제 요청이 만료됐습니다" : "결제에 실패했습니다"),
     };
   }
   if (result === "PENDING") {
     // 결제창이 닫혔는데 아직 결제 전이면 구매자가 닫은 것이다
     return options.popupClosed
-      ? { status: "CANCELED", paymentId, code: "POPUP_CLOSED", message: "결제창을 닫았어요" }
+      ? { status: "CANCELED", paymentId, code: "POPUP_CLOSED", message: "결제창을 닫았습니다" }
       : { status: "PROCESSING", paymentId };
   }
   return { status: "PROCESSING", paymentId };
@@ -236,6 +237,8 @@ export interface StartOptions {
   option: PaymentOption;
   shippingAddress: ShippingAddressInput;
   guest?: GuestInfo;
+  /** 현금영수증 신청 — 계좌이체·가상계좌 옵션에서만 보낸다 */
+  cashReceipt?: CashReceiptRequest;
   returnUrl?: string;
   mode?: PaymentMode;
   /** 클릭 시점에 {@link Payments.prepareWindow}로 미리 연 창. 폼 검증이 비동기라 클릭 태스크를 넘길 때 쓴다 */
@@ -246,6 +249,8 @@ export interface RetryOptions {
   option: PaymentOption;
   /** 생략하면 결제 시작 때의 복귀 주소를 쓴다 */
   returnUrl?: string;
+  /** 현금영수증 신청을 바꾼다. 생략하면 결제 시작 때의 신청을 그대로 둔다 */
+  cashReceipt?: CashReceiptRequest;
   mode?: PaymentMode;
   /** 클릭 시점에 {@link Payments.prepareWindow}로 미리 연 창 */
   window?: PreparedPaymentWindow;
@@ -335,7 +340,7 @@ export function createPayments(options: PaymentsOptions): Payments {
       return; // 주소를 읽지 못하면 검사하지 않는다
     }
     console.warn(
-      `[sayren] returnUrl(${returnUrl})의 origin이 지금 페이지와 달라요 — 결제 서비스는 그 origin으로 결과 메시지를 보내므로 팝업 결과가 도달하지 않고 결제 상태 조회로만 끝나요`,
+      `[sayren] returnUrl(${returnUrl})의 origin이 지금 페이지와 다릅니다 — 결제 서비스는 그 origin으로 결과 메시지를 보내므로 팝업 결과가 도달하지 않고 결제 상태 조회로만 끝납니다`,
     );
   }
 
@@ -364,7 +369,7 @@ export function createPayments(options: PaymentsOptions): Payments {
     if (!given) return prepareWindow({ mode });
     if ((given as Partial<PreparedWindowInternal>)[PREPARED_WINDOW] !== brand) {
       throw new TypeError(
-        "window는 같은 createPayments의 prepareWindow()가 돌려준 핸들이어야 해요",
+        "window는 같은 createPayments의 prepareWindow()가 돌려준 핸들이어야 합니다",
       );
     }
     return given as PreparedWindowInternal;
@@ -512,7 +517,7 @@ export function createPayments(options: PaymentsOptions): Payments {
       if (!returnUrl) {
         prepared.close();
         return Promise.reject(
-          new Error("returnUrl이 필요해요 — createPayments 또는 start에 넘겨 주세요"),
+          new Error("returnUrl이 필요합니다 — createPayments 또는 start에 넘겨 주십시오"),
         );
       }
       warnReturnOrigin(returnUrl, prepared.mode);
@@ -521,6 +526,7 @@ export function createPayments(options: PaymentsOptions): Payments {
           option: startOptions.option,
           shippingAddress: startOptions.shippingAddress,
           guest: startOptions.guest,
+          ...(startOptions.cashReceipt ? { cashReceipt: startOptions.cashReceipt } : {}),
           returnUrl,
         }),
       );
@@ -531,7 +537,11 @@ export function createPayments(options: PaymentsOptions): Payments {
       const returnUrl = retryOptions.returnUrl ?? options.returnUrl;
       warnReturnOrigin(returnUrl, prepared.mode);
       return startWith(prepared, () =>
-        client.payments.retry(paymentId, { option: retryOptions.option, returnUrl }),
+        client.payments.retry(paymentId, {
+          option: retryOptions.option,
+          returnUrl,
+          ...(retryOptions.cashReceipt ? { cashReceipt: retryOptions.cashReceipt } : {}),
+        }),
       );
     },
 
@@ -544,7 +554,7 @@ export function createPayments(options: PaymentsOptions): Payments {
       } catch {
         paymentId = null;
       }
-      if (!paymentId) return { status: "INVALID", message: "결제 정보가 없는 주소예요" };
+      if (!paymentId) return { status: "INVALID", message: "결제 정보가 없는 주소입니다" };
       return paymentResultOf(await client.payments.getStatus(paymentId));
     },
   };

package/src/schemas/checkout.ts

@@ -17,6 +17,44 @@ export const createCheckoutRequestSchema = z
 
 export type CreateCheckoutRequest = z.infer<typeof createCheckoutRequestSchema>;
 
+/** 지역 추가 배송비 구분 — 우편번호로 판정한다 */
+export const remoteAreaSchema = z.enum(["NONE", "JEJU", "ISOLATED"]);
+
+export type RemoteArea = z.infer<typeof remoteAreaSchema>;
+
+/**
+ * 배송비 내역 (이슈 #29) — 배송비를 **몇 번, 왜** 부과했는지다.
+ *
+ * 배송비는 **배송 묶음**마다 붙는다. 같은 출고지 + 같은 배송 정책인 상품은 한 묶음이고 한 번만 낸다.
+ * 제주·도서산간 추가 배송비는 묶음마다 더하고, 무료배송이어도 붙는다.
+ *
+ * 주문서를 만들 때는 배송지를 모르므로 `zipCode`가 null이고 `remoteSurcharge`가 0이다.
+ * 배송지를 입력하면 `POST /storefront/v1/checkout/{checkoutId}/delivery-quote`로 다시 받고,
+ * **결제 시작이 보낸 배송지로 최종 확정한다** — 그래서 주문서 조회 금액과 실제 결제 금액이 다를 수 있다.
+ */
+export const checkoutDeliverySchema = z.object({
+  baseFee: z.number().int().describe("기본 배송비 합계. 묶음마다 부과한 금액의 합이다"),
+  remoteSurcharge: z
+    .number()
+    .int()
+    .describe("제주·도서산간 추가 배송비 합계. 묶음마다 붙는다. 배송지를 모르면 0"),
+  remoteArea: remoteAreaSchema.describe("배송지 지역 구분. 배송지를 모르면 NONE"),
+  remoteAreaLabel: z
+    .string()
+    .nullable()
+    .describe("지역 안내 이름(예: 제주특별자치도). 추가 배송비 지역이 아니면 null"),
+  bundleCount: z.number().int().describe("배송 묶음 수 — 배송비를 부과한 횟수다"),
+  freeByThreshold: z
+    .boolean()
+    .describe("스토어 전체 무료배송 기준액을 넘겨 기본 배송비를 면제했는가"),
+  zipCode: z
+    .string()
+    .nullable()
+    .describe("이 금액에 반영한 배송지 우편번호. null이면 배송지 미반영(추가 배송비 0)이다"),
+});
+
+export type CheckoutDelivery = z.infer<typeof checkoutDeliverySchema>;
+
 export const checkoutSessionSchema = z.object({
   checkoutId: z.string(),
   items: z.array(
@@ -36,6 +74,9 @@ export const checkoutSessionSchema = z.object({
     deliveryFee: z.number().int(),
     totalAmount: z.number().int(),
   }),
+  delivery: checkoutDeliverySchema.describe(
+    "배송비 내역. 배송지를 입력하면 금액이 바뀔 수 있다 — 최종 금액은 결제 시작 응답의 `amounts`다",
+  ),
   expiresAt: z.string(),
   paymentOptions: z
     .lazy(() => paymentOptionListSchema)
@@ -45,12 +86,34 @@ export const checkoutSessionSchema = z.object({
   testPayment: z
     .boolean()
     .describe(
-      "지금 결제하면 테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않아요 — 주문서에 테스트 결제 안내를 표시해요. 결제 요청 시점에 스토어 결제 설정으로 다시 정해지니 최종 값은 결제 요청 응답의 `testPayment`예요",
+      "지금 결제하면 테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않습니다 — 주문서에 테스트 결제 안내를 표시합니다. 결제 요청 시점에 스토어 결제 설정으로 다시 정해지니 최종 값은 결제 요청 응답의 `testPayment`입니다",
     ),
 });
 
 export type CheckoutSession = z.infer<typeof checkoutSessionSchema>;
 
+/**
+ * 배송비 미리보기 요청 — 배송지 우편번호로 배송비를 다시 계산한다. 주문서를 바꾸지 않는다(읽기 계산이다).
+ *
+ * 구매자가 배송지를 입력하거나 고칠 때 부르면 제주·도서산간 추가 배송비가 반영된 금액을 미리 보여 줄 수 있다.
+ */
+export const deliveryQuoteRequestSchema = z.object({
+  zipCode: z
+    .string()
+    .regex(/^[0-9]{5}$/, "우편번호 5자리를 입력해 주십시오")
+    .describe("배송지 우편번호 5자리"),
+});
+
+export type DeliveryQuoteRequest = z.infer<typeof deliveryQuoteRequestSchema>;
+
+/** 배송비 미리보기 응답 — 이 배송지로 결제하면 나갈 금액이다 */
+export const deliveryQuoteSchema = z.object({
+  amounts: checkoutSessionSchema.shape.amounts.describe("이 배송지 기준 금액"),
+  delivery: checkoutDeliverySchema,
+});
+
+export type DeliveryQuoteResult = z.infer<typeof deliveryQuoteSchema>;
+
 export const paymentMethodSchema = z.enum([
   "CARD",
   "BANK_TRANSFER",
@@ -127,10 +190,10 @@ export function paymentOptionKey(option: PaymentOption): string {
 
 export const shippingAddressInputSchema = z.object({
   addressId: z.string().optional(),
-  receiverName: z.string().min(1, "수령인명을 입력해주세요").max(50),
+  receiverName: z.string().min(1, "수령인명을 입력해주십시오").max(50),
   phone: z.string().regex(/^01[0-9]{8,9}$/, "연락처 형식이 아닙니다 (예: 01012345678)"),
   zipCode: z.string().regex(/^[0-9]{5}$/, "우편번호는 5자리 숫자입니다"),
-  address1: z.string().min(1, "기본 주소를 입력해주세요"),
+  address1: z.string().min(1, "기본 주소를 입력해주십시오"),
   address2: z.string().optional(),
   deliveryMemo: z.string().max(100).optional(),
   entranceCode: z.string().max(20).optional(),
@@ -147,6 +210,122 @@ export const guestInfoSchema = z.object({
 
 export type GuestInfo = z.infer<typeof guestInfoSchema>;
 
+/** 현금영수증을 신청할 수 있는 결제수단 — 계좌이체·가상계좌 */
+export const CASH_RECEIPT_METHODS = ["BANK_TRANSFER", "VIRTUAL_ACCOUNT"] as const;
+
+/** 이 결제수단으로 현금영수증을 신청할 수 있는가 */
+export function cashReceiptAvailable(method: string): boolean {
+  return (CASH_RECEIPT_METHODS as readonly string[]).includes(method);
+}
+
+/** 현금영수증 용도 — `INCOME_DEDUCTION` 소득공제(개인) · `EXPENSE_PROOF` 지출증빙(사업자) */
+export const cashReceiptTypeSchema = z.enum(["INCOME_DEDUCTION", "EXPENSE_PROOF"]);
+export type CashReceiptType = z.infer<typeof cashReceiptTypeSchema>;
+
+/** 현금영수증 식별 번호 종류 — 휴대폰 번호 · 현금영수증카드 번호 · 사업자등록번호 */
+export type CashReceiptIdentityType = "PHONE" | "CARD" | "BUSINESS";
+
+/**
+ * 주민등록번호·외국인등록번호 형식인가 — 현금영수증 식별 번호로는 받지 않는다.
+ *
+ * 현금영수증카드 번호의 아래 끝(13자리)이 주민등록번호 길이와 겹친다. 개인 식별 번호는 최소로 받는다는 원칙이라
+ * 주민등록번호로 읽히는 값은 카드 번호 자리로도 받지 않는다.
+ *
+ * **13자리 숫자 전부를 막지 않는다.** 13자리 현금영수증카드를 쓰는 구매자가 신청할 수 없게 되기 때문이다.
+ * 대신 주민등록번호 형식 — 생년월일 6자리(월 01~12, 일 01~31) + 성별·세기 코드(1~8, 5~8은 외국인등록번호) — 으로
+ * 판정해 오탐을 줄인다(13자리 숫자 중 이 형식에 걸리는 비율은 약 3%다).
+ *
+ * 검증번호(뒤 1자리 mod 11)까지는 보지 않는다. 한 자리 오타가 난 주민등록번호도 생년월일을 담고 있어 막아야 하고,
+ * 2020년 10월 이후 발급된 외국인등록번호에는 검증번호 규칙이 없다.
+ *
+ * `cashReceiptIdentityTypeOf`와 같이 하이픈·공백은 빼고 판정한다.
+ */
+export function residentNumberLike(identityNumber: string): boolean {
+  const digits = identityNumber.replace(/[\s-]/g, "");
+  if (!/^[0-9]{13}$/.test(digits)) return false;
+  const month = Number(digits.slice(2, 4));
+  const day = Number(digits.slice(4, 6));
+  const genderCode = Number(digits[6]);
+  return month >= 1 && month <= 12 && day >= 1 && day <= 31 && genderCode >= 1 && genderCode <= 8;
+}
+
+/**
+ * 식별 번호 → 종류. 하이픈·공백은 빼고 판정한다. 용도에 맞지 않는 번호면 null이다.
+ * - 소득공제: 휴대폰 번호(01로 시작하는 10~11자리) 또는 현금영수증카드 번호(13~19자리)
+ * - 지출증빙: 사업자등록번호(10자리) 또는 현금영수증카드 번호(13~19자리)
+ *
+ * 자릿수 근거. PG 문서는 식별 번호의 최대 길이만 정하고 종류별 자릿수는 정하지 않는다
+ * (토스페이먼츠 `customerIdentityNumber` "최대 길이는 30자", 소득공제는 휴대폰 번호·현금영수증카드 번호,
+ * 지출증빙은 사업자등록번호: https://docs.tosspayments.com/common/apis/cash-receipt /
+ * 포트원 V2는 종류만 PHONE·CARD·BUSINESS로 나눈다: https://developers.portone.io/api/rest-v2/payment.cashReceipt).
+ * 그래서 자릿수는 국세청이 정하는 발급수단 규격을 따른다 — 홈택스 소비자 발급수단 등록의 카드 번호는
+ * 13~19자리 숫자이고(https://thisthatbase.com/cash-receipts-card-registration/ 가 옮긴 홈택스 안내,
+ * 원본은 https://www.hometax.go.kr/ 소비자 발급수단 관리), 사업자등록번호는 10자리, 휴대폰 번호는 01X + 7~8자리다.
+ * 국세청 자진발급 번호(010-000-1234)도 휴대폰 형식으로 통과한다.
+ */
+export function cashReceiptIdentityTypeOf(
+  type: CashReceiptType,
+  identityNumber: string,
+): CashReceiptIdentityType | null {
+  const digits = identityNumber.replace(/[\s-]/g, "");
+  if (!/^[0-9]+$/.test(digits)) return null;
+  if (residentNumberLike(digits)) return null;
+  if (/^[0-9]{13,19}$/.test(digits)) return "CARD";
+  if (type === "INCOME_DEDUCTION") return /^01[016789][0-9]{7,8}$/.test(digits) ? "PHONE" : null;
+  return /^[0-9]{10}$/.test(digits) ? "BUSINESS" : null;
+}
+
+/**
+ * 현금영수증 신청 — 계좌이체·가상계좌 결제에서만 보낼 수 있다. 결제가 승인되면 sayren이 결제한 PG로 발급하고,
+ * 환불하면 그만큼 취소한다. 식별 번호는 암호화해 저장하고 응답에는 가린 값만 나간다.
+ */
+export const cashReceiptRequestSchema = z
+  .object({
+    type: cashReceiptTypeSchema.describe(
+      "용도. `INCOME_DEDUCTION` 소득공제(개인) · `EXPENSE_PROOF` 지출증빙(사업자)",
+    ),
+    identityNumber: z
+      .string()
+      .max(30)
+      .describe(
+        "식별 번호. 소득공제는 휴대폰 번호(01X + 7~8자리) 또는 현금영수증카드 번호(13~19자리), 지출증빙은 " +
+          "사업자등록번호(10자리) 또는 현금영수증카드 번호(13~19자리). 하이픈은 빼고 읽는다. " +
+          "주민등록번호는 받지 않는다(`RESIDENT_NUMBER_NOT_ALLOWED`)",
+      ),
+  })
+  .superRefine((value, ctx) => {
+    // 주민등록번호는 단순 형식 오류와 가른다 — 구매자에게 다른 번호를 입력하라고 안내해야 하고,
+    // 셀러·개발자가 필드 오류 코드로 이 경로를 집계할 수 있어야 한다.
+    // 필드 오류 코드는 메시지 끝의 `(CODE)`에서 나온다(api `zod-validation.pipe.ts`의 `extractCode`).
+    if (residentNumberLike(value.identityNumber)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identityNumber"],
+        message:
+          "주민등록번호는 현금영수증 식별 번호로 쓸 수 없습니다. " +
+          "휴대폰 번호 또는 현금영수증카드 번호를 입력해주십시오 (RESIDENT_NUMBER_NOT_ALLOWED)",
+      });
+      return;
+    }
+    if (!cashReceiptIdentityTypeOf(value.type, value.identityNumber)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["identityNumber"],
+        message:
+          value.type === "INCOME_DEDUCTION"
+            ? "휴대폰 번호 또는 현금영수증카드 번호를 입력해주십시오"
+            : "사업자등록번호(10자리) 또는 현금영수증카드 번호를 입력해주십시오",
+      });
+    }
+  });
+export type CashReceiptRequest = z.infer<typeof cashReceiptRequestSchema>;
+
+const cashReceiptField = cashReceiptRequestSchema
+  .optional()
+  .describe(
+    "현금영수증 신청. 계좌이체·가상계좌 옵션에서만 보낼 수 있다(그 밖의 옵션이면 400 `CASH_RECEIPT_NOT_AVAILABLE`). 결제가 승인되면 발급한다",
+  );
+
 /**
  * 결제 시작 — 배송지를 확정하고 고른 결제 옵션으로 결제 시도를 연다. 응답의 `payUrl`(결제 서비스)을 팝업(`mode=popup`)이나
  * 전체 페이지로 열면 결제 서비스가 PG 결제창을 띄우고 승인까지 한다. 리다이렉트 결제가 끝나면 구매자는 `returnUrl`로 돌아온다.
@@ -162,14 +341,20 @@ export const startPaymentRequestSchema = z.object({
     ),
   shippingAddress: shippingAddressInputSchema,
   guest: guestInfoSchema.optional(),
+  cashReceipt: cashReceiptField,
 });
 
 export type StartPaymentRequest = z.infer<typeof startPaymentRequestSchema>;
 
-/** 같은 결제에서 다른 결제 옵션으로 다시 시도. `returnUrl`을 생략하면 결제 시작 때의 복귀 주소를 쓴다 */
+/**
+ * 같은 결제에서 다른 결제 옵션으로 다시 시도. `returnUrl`을 생략하면 결제 시작 때의 복귀 주소를 쓴다.
+ * `cashReceipt`를 보내면 현금영수증 신청을 이 값으로 바꾸고, 생략하면 결제 시작 때의 신청을 그대로 둔다
+ * (승인된 결제수단이 계좌이체·가상계좌가 아니면 발급하지 않는다)
+ */
 export const retryPaymentRequestSchema = z.object({
   option: paymentOptionSchema,
   returnUrl: startPaymentRequestSchema.shape.returnUrl.optional(),
+  cashReceipt: cashReceiptField,
 });
 
 export type RetryPaymentRequest = z.infer<typeof retryPaymentRequestSchema>;
@@ -189,6 +374,12 @@ export const paymentStartSchema = z.object({
     .describe(
       "테스트 결제(샌드박스) 여부. true면 실제로 돈이 나가지 않는다 — 결제 화면에 테스트 결제 안내를 표시한다",
     ),
+  amounts: checkoutSessionSchema.shape.amounts.describe(
+    "**확정 결제 금액** — 보낸 배송지로 배송비를 다시 계산한 값이다. 주문서 조회 시점의 `amounts`와 다를 수 있다(제주·도서산간 추가 배송비)",
+  ),
+  delivery: checkoutDeliverySchema.describe(
+    "확정 배송비 내역. `zipCode`는 보낸 배송지의 우편번호다",
+  ),
 });
 
 export type PaymentStart = z.infer<typeof paymentStartSchema>;
@@ -231,14 +422,14 @@ export const paymentStatusSchema = z.object({
     .string()
     .describe(
       "결제 상태. 현재 값은 `pending` 결제 대기 · `processing` 승인 확인 중 · `completed` 결제 완료(주문 생성) · `failed` 실패 · " +
-        "`expired` 만료예요. 상태가 추가될 수 있어 문자열로 받아요 — 모르는 값은 `processing`처럼 다루고 계속 조회하세요",
+        "`expired` 만료입니다. 상태가 추가될 수 있어 문자열로 받습니다 — 모르는 값은 `processing`처럼 다루고 계속 조회하십시오",
     ),
   result: z
     .string()
     .describe(
       "화면 분기용 결과. `COMPLETED` 결제 완료 · `PROCESSING` 결과 확인 중 · `CANCELED` 구매자가 결제창을 닫음 · " +
-        "`FAILED` 결제 실패(다른 결제 옵션으로 재시도 가능) · `EXPIRED` 결제 요청 만료 · `PENDING` 결제 전이에요. " +
-        "값이 추가될 수 있어 문자열로 받아요 — 모르는 값은 `PROCESSING`처럼 다루세요",
+        "`FAILED` 결제 실패(다른 결제 옵션으로 재시도 가능) · `EXPIRED` 결제 요청 만료 · `PENDING` 결제 전입니다. " +
+        "값이 추가될 수 있어 문자열로 받습니다 — 모르는 값은 `PROCESSING`처럼 다루십시오",
     ),
   orderId: z.string().nullable().describe("결제가 완료됐으면 주문 번호, 그 외에는 null"),
   lastFailure: z
@@ -250,14 +441,14 @@ export const paymentStatusSchema = z.object({
       code: z
         .string()
         .nullable()
-        .describe("PG가 준 실패 코드. 내부 사유는 null이에요. 화면 분기는 `category`로 하세요"),
+        .describe("PG가 준 실패 코드. 내부 사유는 null입니다. 화면 분기는 `category`로 하십시오"),
       message: z.string().nullable().describe("구매자에게 보여 줄 안내 문구"),
     })
     .nullable()
     .describe("현재 결제 시도가 실패·취소로 끝났으면 그 내용, 아니면 null"),
   testPayment: z
     .boolean()
-    .describe("테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않았어요"),
+    .describe("테스트 결제(샌드박스)인가. true면 실제로 돈이 나가지 않았습니다"),
   expiresAt: z.string().describe("결제 요청 만료 시각"),
 });
 

package/src/schemas/claim.ts

@@ -56,6 +56,24 @@ export const createClaimResultSchema = z.object({
 
 export type CreateClaimResult = z.infer<typeof createClaimResultSchema>;
 
+/**
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 상품이 반품지를 따로 지정했으면 그 주소다.
+ *
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+ */
+export const claimReturnAddressSchema = z.object({
+  name: z.string().describe("주소 이름(셀러가 붙인 별칭). 예: 본사 물류센터"),
+  contactName: z.string().describe("수취인 이름"),
+  phone: z.string().describe("연락처"),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+});
+
+export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
+
 export const myClaimSchema = z.object({
   claimId: z.string(),
   type: claimTypeSchema,
@@ -81,6 +99,11 @@ export const myClaimSchema = z.object({
         "이 필드가 생기기 전에 접수된 클레임은 null이다",
     ),
   rejectReason: z.string().nullable(),
+  returnAddress: claimReturnAddressSchema
+    .nullable()
+    .describe(
+      "반품·교환 물건을 보낼 반품지(이슈 #30). 직접 보내는 수거 안내에 쓴다. 취소 클레임은 null",
+    ),
   requestedAt: z.string(),
   completedAt: z.string().nullable(),
 });

package/src/schemas/order.ts

@@ -73,24 +73,57 @@ export const myOrderSchema = z.object({
   testPayment: z
     .boolean()
     .describe(
-      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 나가지 않았어요 — 주문 화면에 테스트 결제 배지를 표시해요",
+      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 나가지 않았습니다 — 주문 화면에 테스트 결제 배지를 표시합니다",
     ),
 });
 
 export type MyOrder = z.infer<typeof myOrderSchema>;
 
+/**
+ * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+ * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+ */
+export const trackingStageResponseSchema = z.string();
+
 export const deliveryTrackingSchema = z.object({
   carrierName: z.string(),
   trackingNumber: z.string(),
   trackingUrl: z.url(),
   status: z.enum(["DISPATCHED", "DELIVERING", "DELIVERED"]),
-  trackingEvents: z.array(
-    z.object({
-      status: z.string(),
-      location: z.string(),
-      occurredAt: z.string(),
-    }),
-  ),
+  trackingEvents: z
+    .array(
+      z.object({
+        status: z.string().describe("택배사가 알려 준 처리 내용(예: 집화처리, 배송출발)"),
+        location: z.string().describe("처리 장소. 모르면 빈 문자열"),
+        occurredAt: z.string(),
+        stage: trackingStageResponseSchema
+          .nullable()
+          .optional()
+          .default(null)
+          .describe(
+            "이 이벤트의 추적 단계. 배달 실패처럼 단계로 나눌 수 없는 이벤트는 null. 서버는 항상 싣는다. " +
+              "현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 값이 추가될 수 있어 문자열로 받는다",
+          ),
+      }),
+    )
+    .describe("배송 추적 이력. 시각 오름차순(오래된 것부터)"),
+  trackingStage: trackingStageResponseSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "현재 추적 단계. 택배 발송이 아니거나, 아직 조회되지 않았거나, 택배사 전산에 송장이 없으면 null. 서버는 항상 싣는다. " +
+        "현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·`OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)이고 " +
+        "값이 추가될 수 있어 문자열로 받는다",
+    ),
+  trackingCheckedAt: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "택배사에서 추적 정보를 마지막으로 받아 온 시각(ISO 8601). 받아 온 적이 없으면 null. 서버는 항상 싣는다",
+    ),
 });
 
 export type DeliveryTracking = z.infer<typeof deliveryTrackingSchema>;

package/src/schemas/review.ts

@@ -40,7 +40,7 @@ export type WritableReview = z.infer<typeof writableReviewSchema>;
 
 export const createReviewRequestSchema = z.object({
   rating: z.number().int().min(1).max(5),
-  content: z.string().min(10, "리뷰는 10자 이상 작성해주세요").max(2000),
+  content: z.string().min(10, "리뷰는 10자 이상 작성해주십시오").max(2000),
   images: z.array(z.url()).max(5).optional(),
 });