@sayren/store-sdk 0.63.0 → 0.65.0

package/src/schemas/ai.ts

@@ -399,6 +399,25 @@ export const storeSetupBriefSchema = z.object({
 });
 export type StoreSetupBrief = z.infer<typeof storeSetupBriefSchema>;
 
+/**
+ * 보내는 사람의 시간대(IANA 이름, 예 `Asia/Seoul`) — 브라우저 `Intl.DateTimeFormat().resolvedOptions().timeZone`. AI는 시각을 이 시간대로 쓴다.
+ * 생략하면 `Asia/Seoul`이다
+ */
+export const aiTimeZoneSchema = z
+  .string()
+  .max(64)
+  .refine(
+    (value) => {
+      try {
+        new Intl.DateTimeFormat("en-US", { timeZone: value });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { message: "IANA 시간대 이름이어야 합니다" },
+  );
+
 export const createAiConversationRequestSchema = strictRequest(
   z.object({
     /** 웹사이트에서 남긴 초안(#124 M2) — 연결한 사용자만 쓴다. 주면 첫 메시지로 실행을 시작한다 */
@@ -407,6 +426,8 @@ export const createAiConversationRequestSchema = strictRequest(
     brief: storeSetupBriefSchema.optional(),
     /** AI 종류 — 주지 않으면 초안으로 시작하면 `DESIGNER`, 아니면 `STORE`다 */
     agent: aiAgentSchema.optional(),
+    /** 첫 실행의 시간대(`draftId`로 시작할 때) */
+    timeZone: aiTimeZoneSchema.optional(),
   }),
 );
 export type CreateAiConversationRequest = z.infer<typeof createAiConversationRequestSchema>;
@@ -429,6 +450,8 @@ export const sendAiMessageRequestSchema = strictRequest(
       selection: aiPreviewSelectionSchema.optional(),
       /** 디자인 탭에서 고른 아트보드(2026-10-14) — 모델은 그 아트보드를 기준으로 고친다 */
       designSelection: aiDesignSelectionSchema.optional(),
+      /** 보내는 사람의 시간대 — 이 실행의 AI가 시각을 이 시간대로 쓴다 */
+      timeZone: aiTimeZoneSchema.optional(),
     })
     .refine((body) => body.text.length > 0 || body.attachments.length > 0, {
       message: "내용이나 첨부가 있어야 합니다",

package/src/schemas/app-manifest.ts

@@ -45,7 +45,7 @@ export const appHandleSchema = z
 
 /**
  * 설치 앱에 열지 않는 스코프 — 구성원(초대로 권한 상승), 상점 설정 전반(`storefrontOrigins`로 소셜 로그인 code 가로채기), 스토어 웹훅
- * (앱 구독으로 대체, 제거 뒤에도 남는 문제), 스토어프론트 편집·발행, 감사 로그. 커스텀 연동은 계정 액세스 토큰(#71)이 맡는다
+ * (앱 구독으로 대체, 제거 뒤에도 남는 문제), 스토어프론트 편집·발행, 감사 로그, 구매자 개인정보 원문(#217). 커스텀 연동은 계정 액세스 토큰(#71)이 맡는다
  */
 export const NON_INSTALLABLE_SCOPES: ReadonlySet<string> = new Set([
   "member:r",
@@ -56,6 +56,7 @@ export const NON_INSTALLABLE_SCOPES: ReadonlySet<string> = new Set([
   "storefront:r",
   "storefront:rw",
   "audit:r",
+  "privacy:r",
 ]);
 
 /** 앱이 요청할 수 있는 스코프 — 카탈로그 전체에서 위를 뺀 것 */
@@ -134,6 +135,7 @@ export const APP_EVENT_SCOPES: Record<AppEventType, string | null> = {
   "ORDER.FLOW_NOTIFICATION": "order:r",
   "ORDER.FLOW_STATE_CHANGED": "order:r",
   "ORDER.PAYMENT_ADDED": "order:r",
+  "ORDER.REFUNDED": "order:r",
   "ORDER.PAYMENT_REQUESTED": "order:r",
   "CLAIM.CANCEL_REQUESTED": "claim:r",
   "CLAIM.RETURN_REQUESTED": "claim:r",

package/src/schemas/claim.ts

@@ -181,6 +181,41 @@ export const rejectClaimRequestSchema = strictRequest(
 
 export type RejectClaimRequest = z.infer<typeof rejectClaimRequestSchema>;
 
+/** `POST /v1/claims/{claimId}/approve` 요청 — 본문은 생략할 수 있다 */
+export const approveClaimRequestSchema = strictRequest(
+  z.object({
+    deductAmount: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "환불액에서 뺄 추가 차감(원). 생략하면 주문 흐름이 접수 때 계산한 차감액, 그것도 없으면 0이다",
+      ),
+    refundAmount: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "최종 현금 환불액(#365, 원). 생략하면 서버 계산값이다. 배송비 환불 여부·귀책과 무관하게 판매자가 정한다. " +
+          "배송비·쿠폰 정산 기록과 적립금 반환은 계산값대로 하고 현금만 이 값이다. 결제 잔액(`availableRefundAmount`)을 넘으면 409 `REFUND_EXCEEDS_BALANCE`. " +
+          "`deductAmount`와 함께 주면 400이다. 응답·웹훅의 `calculatedRefundAmount`가 서버 계산값이다",
+      ),
+    holdRefund: z
+      .boolean()
+      .optional()
+      .describe(
+        "true면 승인만 하고 결제 환불은 대기로 남긴다(#115). 결제 상세의 `POST /v1/payments/refunds/{refundId}/process`로 따로 환불한다",
+      ),
+  }),
+).refine((body) => body.refundAmount === undefined || body.deductAmount === undefined, {
+  message: "refundAmount와 deductAmount는 함께 줄 수 없습니다",
+  path: ["refundAmount"],
+});
+
+export type ApproveClaimRequest = z.infer<typeof approveClaimRequestSchema>;
+
 export const approveClaimResultSchema = z.object({
   claimId: z.string(),
   refundAmount: z
@@ -188,8 +223,16 @@ export const approveClaimResultSchema = z.object({
     .int()
     .describe(
       "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − " +
-        "쿠폰 조건 미달 차감(`couponChargeAmount`) + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)",
+        "쿠폰 조건 미달 차감(`couponChargeAmount`) + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`). 판매자가 `refundAmount`를 정했으면 그 값이다",
     ),
+  calculatedRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      "서버가 계산한 현금 환불액(#365). 판매자가 `refundAmount`를 정하지 않았으면 `refundAmount`와 같다. 이 필드가 없는 이전 응답은 `refundAmount`와 같다고 읽는다",
+    ),
+
   deductAmount: z.number().int().describe("승인 때 셀러가 추가로 차감한 금액"),
   quantity: z.number().int().describe("환불한 수량"),
   deliveryFeeRefundAmount: z

package/src/schemas/customer.ts

@@ -54,6 +54,79 @@ export const customerSummarySchema = z
   .extend(customerStatsSchema.shape);
 export type CustomerSummary = z.infer<typeof customerSummarySchema>;
 
+// ── 내보내기 (이슈 #217) ────────────────────────────────────
+
+/** 내보내기에서 고를 수 있는 필드 */
+export const customerExportFieldSchema = z
+  .enum([
+    "name",
+    "email",
+    "phone",
+    "joinedAt",
+    "orderCount",
+    "totalPaid",
+    "lastOrderedAt",
+    "point",
+    "marketingAgreed",
+    "marketingUpdatedAt",
+    "birthdate",
+    "gender",
+    "defaultAddress",
+  ])
+  .describe(
+    "내보낼 필드. `marketingUpdatedAt`은 마케팅 수신 동의·철회가 마지막으로 바뀐 시각, `defaultAddress`는 기본 배송지다",
+  );
+export type CustomerExportField = z.infer<typeof customerExportFieldSchema>;
+
+export const CUSTOMER_EXPORT_MAX_SIZE = 500;
+
+/** `GET /v1/customers/export` 쿼리 — 목록과 같은 조건 + 내보낼 필드 */
+export const customerExportQuerySchema = customerListQuerySchema.extend({
+  fields: z
+    .string()
+    .describe(
+      "내보낼 필드(쉼표로 구분, 하나 이상). `customerExportFieldSchema`의 값이다. 모르는 값은 400이다",
+    ),
+  ...pageQueryShape({ defaultSize: 100, maxSize: CUSTOMER_EXPORT_MAX_SIZE }),
+});
+
+/** 내보내기 기본 배송지 — 휴대폰은 `phone`과 같은 규칙으로 가린다 */
+export const customerExportAddressSchema = z.object({
+  receiverName: z.string(),
+  phone: z.string().nullable(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+  countryCode: z.string(),
+  city: z.string().nullable(),
+  region: z.string().nullable(),
+});
+
+/** 내보내기 한 줄 — 고른 필드만 싣는다 */
+export const customerExportRowSchema = z.object({
+  customerId: z.string(),
+  name: z.string().optional(),
+  email: z.string().nullable().optional(),
+  phone: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "휴대폰. 스코프 `privacy:r`이 있으면 전체 번호, 없으면 가운데를 가린 번호(`010-****-1234`)",
+    ),
+  joinedAt: z.string().optional(),
+  orderCount: z.number().int().optional(),
+  totalPaid: z.number().int().optional().describe("구매 금액(원) — 목록과 같은 기준"),
+  lastOrderedAt: z.string().nullable().optional(),
+  point: z.number().int().optional(),
+  marketingAgreed: z.boolean().optional(),
+  marketingUpdatedAt: z.string().nullable().optional(),
+  birthdate: z.string().nullable().optional(),
+  gender: z.string().nullable().optional(),
+  defaultAddress: customerExportAddressSchema.nullable().optional(),
+});
+export type CustomerExportRow = z.infer<typeof customerExportRowSchema>;
+
 export const customerAddressSchema = z.object({
   addressId: z.string(),
   alias: z.string(),
@@ -148,12 +221,18 @@ export const customerConsentListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
-/** 구매자 상세 — 휴대폰 전체를 보여 준다 */
+/**
+ * 구매자 상세 — 휴대폰(구매자·배송지)은 스코프 `privacy:r`이 있으면 전체 번호, 없으면 가린 번호(`010-****-1234`)다(#217).
+ * 가린 경우 `userinfo.phone_number`는 싣지 않는다
+ */
 export const customerDetailSchema = z.object({
   customerId: z.string(),
   name: z.string(),
   email: z.string().nullable(),
-  phone: z.string().nullable(),
+  phone: z
+    .string()
+    .nullable()
+    .describe("휴대폰. `privacy:r`이 있으면 전체 번호, 없으면 가운데를 가린 번호"),
   joinedAt: z.string(),
   point: z.number().int(),
   marketingAgreed: z.boolean(),

package/src/schemas/misc.ts

@@ -169,6 +169,8 @@ export const eventTypeSchema = z
     "ORDER.PAYMENT_ADDED",
     // 흐름 노드 「결제 요청」이 결제 링크를 만듦(이슈 #117)
     "ORDER.PAYMENT_REQUESTED",
+    // 판매자가 금액만 환불함(#365)
+    "ORDER.REFUNDED",
   ])
   .describe(
     "웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",

package/src/schemas/order.ts

@@ -690,6 +690,16 @@ export const cancelBySellerRequestSchema = strictRequest(
       .describe(
         "환불액에서 뺄 추가 차감(#301, 원). 생략하면 0이다. 현금에서 먼저 빼고 모자란 몫만 돌려줄 적립금에서 뺀다. 환불 원장·`ORDER.CANCELED` 웹훅에 따로 남는다",
       ),
+    refundAmount: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "최종 현금 환불액(#365, 원). 생략하면 서버 계산값이다. 배송비 환불 여부·귀책과 무관하게 판매자가 정한다. " +
+          "배송비·쿠폰 정산 기록과 적립금 반환은 계산값대로 하고 현금만 이 값이다. 결제 잔액(`availableRefundAmount`)을 넘으면 409 `REFUND_EXCEEDS_BALANCE`. " +
+          "`deductAmount`와 함께 주면 400이다. 응답·웹훅의 `calculatedRefundAmount`가 서버 계산값이다",
+      ),
     restock: z
       .boolean()
       .optional()
@@ -705,10 +715,43 @@ export const cancelBySellerRequestSchema = strictRequest(
           "회원 잔액이 모자라면 있는 만큼만 회수한다(리뷰 적립 회수와 같은 규칙)",
       ),
   }),
-);
+).refine((body) => body.refundAmount === undefined || body.deductAmount === undefined, {
+  message: "refundAmount와 deductAmount는 함께 줄 수 없습니다",
+  path: ["refundAmount"],
+});
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 
+/**
+ * 금액만 환불 요청(#365) — `POST /v1/orders/{orderId}/refunds`. 주문상품 상태·수량·재고·적립금·쿠폰·배송비 정산을 바꾸지 않고
+ * 결제에서 금액만 돌려준다. 헤더 `Idempotency-Key`가 필수다
+ */
+export const sellerRefundRequestSchema = strictRequest(
+  z.object({
+    amount: z
+      .number()
+      .int()
+      .min(1)
+      .describe(
+        "돌려줄 현금 (원). 결제의 남은 금액(결제 상세 `availableRefundAmount`)을 넘으면 409 `REFUND_EXCEEDS_BALANCE`",
+      ),
+    reason: z
+      .string()
+      .trim()
+      .min(1)
+      .max(500)
+      .describe("환불 사유. 감사 로그와 결제 상세 환불 이력에 남는다"),
+    paymentId: z
+      .string()
+      .optional()
+      .describe(
+        "환불할 결제(주문 응답 `payments[].paymentId`). 생략하면 주문의 첫 결제다. 추가 결제가 있는 주문은 이 값으로 고른다",
+      ),
+  }),
+);
+
+export type SellerRefundRequest = z.infer<typeof sellerRefundRequestSchema>;
+
 /**
  * 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 배송 없는 주문상품(`MANUAL`)을
  * 제공 완료(`DELIVERED`)로 바꾼다.
@@ -744,7 +787,14 @@ export const cancelBySellerResultSchema = z.object({
     .int()
     .describe(
       "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
-        "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)",
+        "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`). 판매자가 `refundAmount`를 정했으면 그 값이다",
+    ),
+  calculatedRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      "서버가 계산한 현금 환불액(#365). 판매자가 `refundAmount`를 정하지 않았으면 `refundAmount`와 같다. 이 필드가 없는 이전 응답은 `refundAmount`와 같다고 읽는다",
     ),
   quantity: z.number().int().describe("취소한 수량"),
   canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),

package/src/schemas/payment.ts

@@ -910,10 +910,21 @@ export const paymentRefundRecordSchema = z.object({
     .optional()
     .default(0)
     .describe("같은 환불에서 돌려준 적립금 (#93). 적립금을 쓰지 않은 결제는 0"),
+  calculatedAmount: z
+    .number()
+    .int()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "서버가 계산한 현금 환불액 (#365). 판매자가 최종 금액을 정했으면 `amount`와 다르다. 계산이 없는 환불(결제 오류 보상 등)과 이전 환불은 null이다",
+    ),
   reason: z.string().describe("환불 사유 코드"),
   kind: z
     .string()
-    .describe("환불 원인 — SELLER_CANCEL·CLAIM·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다"),
+    .describe(
+      "환불 원인 — SELLER_CANCEL·CLAIM·SELLER_REFUND(금액만 환불)·COMPENSATION·DUPLICATE. 새 값이 추가될 수 있다",
+    ),
   status: z
     .string()
     .describe(
@@ -927,6 +938,13 @@ export type PaymentRefundRecord = z.infer<typeof paymentRefundRecordSchema>;
 
 export const paymentRecordDetailSchema = paymentRecordSchema.extend({
   refundableAmount: z.number().int().describe("환불 가능 잔액 = 승인 금액 - 환불 완료 금액"),
+  availableRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      "지금 더 환불할 수 있는 금액 = 승인 금액 - (환불 완료 + 처리 중 + 대기 환불). 이보다 큰 환불은 409 `REFUND_EXCEEDS_BALANCE`다. 승인되지 않은 결제는 0. 이 필드가 없는 이전 api는 `refundableAmount`로 읽는다",
+    ),
   merchantId: z
     .string()
     .nullable()

package/src/schemas/scope-descriptions.ts

@@ -25,6 +25,10 @@ export const SCOPE_DESCRIPTIONS: Record<StoreScopeResource, { r: string; rw: str
     r: "위치별 재고와 재고 변동 내역을 읽습니다",
     rw: "재고를 조정·실사하고 위치 사이에서 이동합니다",
   },
+  privacy: {
+    r: "구매자 개인정보(휴대폰 전체 번호)를 내보냅니다",
+    rw: "구매자 개인정보(휴대폰 전체 번호)를 내보냅니다",
+  },
 };
 
 /** `{resource}:{r|rw}` → 문장. 카탈로그에 없는 스코프는 null */

package/src/schemas/scope.ts

@@ -35,6 +35,8 @@ export const STORE_SCOPE_RESOURCES = {
   flow: ["r", "rw"],
   // 위치별 재고·재고 조정·이동·변동 내역(이슈 #132) — 기존 재고 표면(조합 재고 수정, 상품·옵션의 `stockQuantity`)은 product 스코프다
   inventory: ["r", "rw"],
+  // 구매자 개인정보 원문(이슈 #217) — 내보내기의 휴대폰 전체 번호. 없으면 가린 번호다. 쓰기 API가 없어 `r`만 존재한다
+  privacy: ["r"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -74,6 +76,7 @@ export const STORE_ROLE_SCOPES = {
     "storefront:rw",
     "flow:rw",
     "inventory:rw",
+    "privacy:r",
   ],
   ADMIN: [
     "product:rw",
@@ -92,6 +95,7 @@ export const STORE_ROLE_SCOPES = {
     "storefront:rw",
     "flow:rw",
     "inventory:rw",
+    "privacy:r",
   ],
   STAFF: [
     "product:rw",

package/src/schemas/webhook-event.ts

@@ -177,7 +177,14 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .describe(
       "환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
         "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)이다. " +
-        "결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다",
+        "판매자가 `refundAmount`를 정했으면 그 값이다. 결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다",
+    ),
+  calculatedRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      "서버가 계산한 환불액 (원, #365). 판매자가 최종 금액을 정하지 않았으면 `refundAmount`와 같다. 이 필드가 없는 이전 이벤트는 `refundAmount`와 같다고 읽는다",
     ),
   deliveryFeeRefundAmount: z.number().int().describe("환불액에 포함된 배송비 (원)"),
   deliveryFeeChargeAmount: z
@@ -257,9 +264,16 @@ export const claimWebhookEventDataSchema = z.object({
     .optional()
     .default(null)
     .describe(
-      "환불액 (원). 배송비 환불을 포함하고 배송비 차감·추가 차감을 뺀 실제 금액이다. " +
+      "환불액 (원). 배송비 환불을 포함하고 배송비 차감·추가 차감을 뺀 실제 금액이다. 판매자가 승인에 최종 금액을 정했으면 그 값이다. " +
         "환불이 확정되지 않은 접수 이벤트는 예상 환불액이고, 교환처럼 환불이 없으면 null이다",
     ),
+  calculatedRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .describe(
+      "서버가 계산한 환불액 (원, #365) — 완료 이벤트(`CLAIM.COMPLETED`)에만 싣는다. 판매자가 최종 금액을 정하지 않았으면 `refundAmount`와 같다. 이 필드가 없는 이벤트는 `refundAmount`와 같다고 읽는다",
+    ),
   deliveryFeeRefundAmount: z
     .number()
     .int()
@@ -542,6 +556,27 @@ export const orderPaymentRequestedWebhookEventSchema = z.object({
   data: orderPaymentRequestedWebhookEventDataSchema,
 });
 
+/**
+ * 금액만 환불(#365) — 판매자가 주문상품을 취소하지 않고 결제에서 금액만 돌려주기로 했다. 결제사 환불 결과는 결제 상세
+ * (`GET /v1/payments/{paymentId}`의 `refunds[]`, `refundId`)로 확인한다. 개인정보는 싣지 않는다
+ */
+export const orderRefundedWebhookEventDataSchema = z.object({
+  orderId: z.string().describe("주문 ID"),
+  orderNo: z.string().nullable().describe("주문번호. 번호 체계 이전 주문은 null"),
+  paymentId: z.string().describe("환불한 결제"),
+  refundId: z.string().describe("환불 이력 id(결제 상세 `refunds[].refundId`)"),
+  amount: z.number().int().describe("돌려준 현금 (원)"),
+  reason: z.string().describe("판매자가 적은 환불 사유"),
+  currency: z.string().describe("주문 통화"),
+  testPayment: z.boolean(),
+});
+
+export const orderRefundedWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("ORDER.REFUNDED"),
+  data: orderRefundedWebhookEventDataSchema,
+});
+
 /** 웹훅 요청 본문. `type`으로 판별하며 `data` 형태가 타입별로 다르다 */
 export const webhookEventSchema = z
   .discriminatedUnion("type", [
@@ -557,6 +592,7 @@ export const webhookEventSchema = z
     inventoryChangedWebhookEventSchema,
     orderPaymentAddedWebhookEventSchema,
     orderPaymentRequestedWebhookEventSchema,
+    orderRefundedWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",